OpenSimulator - User contributions [en]

Related Software

2009-12-25T00:48:22Z

Nlin: Updating information about Rei

__NOTOC__
{{Template:Quicklinks}}
 
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Related_Software | Related Software]]
 

{{content}}
== Introduction ==
This is a page which lists software packages that are related to OpenSimulator but are not part of the core project. Opensimulator is not responsible for the content referenced by these links.

== Dependent Software ==
OpenSim depends on many other libraries to function. You get these with your default distribution of OpenSim, but for more information on each project you should see it's home page
* [http://libsecondlife.org libopenmetaverse]
* [http://www.ode.org ODE] ODE is an open source, high performance library for simulating rigid body dynamics.
* [http://www.codeplex.com/Json json.net] JSON (JavaScript Object Notation) is a lightweight data-interchange format.
* [http://www.mono-project.com mono] Mono is a cross platform, open source .NET development framework.
* [http://nant.sourceforge.net nant] NAnt is a free .NET build tool.
* [http://www.realxtend.org realXtend] realXtend viewer and server working with OGRE and support MESH.
* [http://subversion.tigris.org Subversion] Subversion is an open source version control system.
* [http://www.python.org Python] Python is a dynamic object-oriented programming language that can be used for many kinds of software development.
* [http://xmlrpccs.sf.net XmlRpcCS]
* [http://www.nunit.org NUnit]
* [http://sourceforge.net/projects/dnpb Prebuild]
* [http://dotnetopenmail.sourceforge.net DotNetOpenMail]
* [http://www.prototypejs.org Prototype JavaScript Framework ajax]
* [http://nini.sourceforge.net Nini]
* [http://logging.apache.org/log4net log4net]
* [http://gtcache.sourceforge.net GlynnTucker.Cache]
* '''todo:''' list the rest of the contents of bin here

== OpenSim Viewers ==
The following 3D Viewers are known to work with OpenSim. We take no responsibility for their bugs, features, or lack there of.
* [http://get.secondlife.com Official Second Life (tm) Viewer]
* [http://opensim-viewer.sourceforge.net Hippo Viewer]
* [http://imprudenceviewer.org Imprudence Viewer]
* [http://www.realxtend.org realXtend Viewer]
* [http://www.meerkatviewer.org Meerkat Viewer]
* [http://forge.opensimulator.org/gf/project/idealistviewer/ IdealistViewer]
* [http://3di-rei.org/ 3Di Viewer Rei] - Web Browser based Viewer in C#, JavaScript integration, BSD.

== OpenSim Forge Projects ==
OpenSimulator now has a [http://forge.opensimulator.org/gf/ forge] for related software.
* [http://forge.opensimulator.org/gf/project/osinstaller OpenSim Installers]
* [http://forge.opensimulator.org/gf/project/opensim-viewer Hippo OpenSim Viewer]
* [http://forge.opensimulator.org/gf/project/opensimwi/ OpenSimWi(Redux)]
* [http://forge.opensimulator.org/gf/project/openterrains/ Open Source Terrain Textures]
* [http://forge.opensimulator.org/gf/project/ogp/ OGP Patches]
* [http://forge.opensimulator.org/gf/project/xenki/ Xenki Viewer]
* [http://forge.opensimulator.org/gf/project/ostray/ OSTray]
* [http://forge.opensimulator.org/gf/project/sllauncher/ SL Launcher]
* [http://forge.opensimulator.org/gf/project/openusermanual/ Open User Manual]
* [http://forge.opensimulator.org/gf/project/deepservers/ DeepServer (ASP.NET Grid Server)]
* [http://forge.opensimulator.org/gf/project/modrex/ realXtend Modules]
'''todo''' list some of the top opensim forge projects.

==Modules==

These are either application or region modules which can be added to the OpenSim core distribution to provide extra functionality.

None are listed yet!

==Other related software==
These are independent implementations of OpenSimulator services, such as the user server or the inventory server (also known as UGAI).

* [http://openugai.sourceforge.net/ OpenUGAI] - A Perl implementation of the UGAI services which runs within Apache.
* [http://www.ics.uci.edu/~lopes/terraingen/ Terraingen] - Tool for producing OpenSim terrains from USGS DEM files.
* [[RegionGenerator]] - Generates Region XML Files
* [http://www.secondinventory.com/ Second Inventory] - A Windows based client that can be used to back up and restore objects from Second Life™ as well as from various OpenSimulator based grids. It allows you to back up objects from the Second Life™ main grid, and restore them into OpenSimulator grids. It is still a bit primitive and sometimes can be flaky. This software is in no way supported by the OpenSIM team, please contact its creator for support.
* [http://www.metabolt.net/ METAbolt] - METAbolt is a non-graphical (text based) viewer. It's light weight and cross grid, which means it will work in Second Life™ as well as other grids that are based on OpenSIM. The viewer is Open Source so it's free. Currently METAbolt is only available for Windows platforms.
* [http://3di-opensim.com/en/ 3Di OpenSim Enterpise] - Business service based on OpenSim.
* [http://3di-rei.org/ 3Di Viewer Rei] - Web Browser based Viewer.
* [http://www.nsl.tuis.ac.jp/xoops/modules/xpwiki/?sl_proxy%20%28E%29 sl_proxy] - sl_proxy is a Proxy System for Second Life™ and OpenSim to beyond firewall.
* [http://www.nsl.tuis.ac.jp/xoops/modules/xpwiki/?XoopenSim XoopenSim] - OpenSim WEB Interface for Xoops Cube. This module was made by remodeling [http://forge.opensimulator.org/gf/project/opensimwi/ OpenSimWi(Redux)]. (Sorry. This page is Japanese only.)
* [http://www.nsl.tuis.ac.jp/xoops/modules/xpwiki/?OpenSim%2FMoneyServer Money Server (NSL Version)] - This Money Server is modified version of [http://forge.opensimulator.org/gf/project/currency/ DTL Currency Processing] for Linux/Unix.
* [http://www.nsl.tuis.ac.jp/xoops/modules/d3downloads/index.php?page=singlefile&cid=8&lid=8 Unofficial NSL Patch for OpenSim 0.6.7] - The phenomenon of avatar's falling to the hell is corrected at the boundary of SIM and empty region. etc.etc.

==Addons==

*** PLEASE DO NOT ASK THE OPENSIMULATOR TEAM FOR SUPPPORT ABOUT THESE ADD-ON PACKAGES

==Concepts==
* [http://www.cs.cmu.edu/~johnny/projects/wii/ 3D Head Tracking Software] - The idea here is that Johnny has written an application that will allow real3d perspective using a WiiMote & a modified set of safety glasses. Johnny includes all of the source and several sample applications to get this moving forward. Would someone like to pick this up and build us a real3D interface for the SL browser? It's not as hard as you think.

* [http://en.wikipedia.org/wiki/Edusim Edusim on Opensim] - Edusim is a [http://en.wikipedia.org/wiki/Cave_Automatic_Virtual_Environment Cave Automatic Virtual Environment] based concept of lesson driven 3D virtual worlds on the ''classroom interactive whiteboard or classroom interactive surface''. Currently Edusim on Opencobalt Cobalt exists but tweaking a client and making Opensim "finger friendly" would seem to be a relatively straight forward task.

= See Also =

* [[:Category:Getting Started|Getting Started]]
* [[:Category:Tech Reference|Technical Reference Pages]]
* [[:Category:Development|Development]]
* [[Status|Main Status Page]]

[[Category:Users]]
[[Category:Support]]
[[Category:Tech Reference]]
[[Category:Help]]
[[Category:Configuration]]
[[Category:Getting_Started]]
[[Category:Development]]
[[Category:Todo]]

Talk:NINJA Physics

2009-01-14T05:39:42Z

Nlin:

There used to be functionality like this in Second Life (at least the sources seems to indicate this).

What happened to it? Are there lessons to be learned?

* This is a good question and I unfortunately don't know the answer. All I know, from second hand accounts, is that SL used to support it, but it was buggy and unstable, so it was removed. I'd love to hear more about it and why they abandoned it. (The protocol still contains references to joint information fields, so maybe we can use those fields in the future.) [[User:Nlin|Nlin]] 05:39, 14 January 2009 (UTC)

NINJA Physics

2009-01-13T04:38:43Z

Nlin: /* Editing and Naming limitations */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Separate from NINJA Physics, other activity has recently accelerated on LSL script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object, also called a joint prim, is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the affected prims' movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate. A joint prim only affects the physics simulation if the joint prim's "[x] Physical" property is activated.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint prim.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. Technically, joints are implemented in the physics engine as mathematical (equality or inequality) constraints on the position and/or velocity of rigid bodies, so they constrain the admissible region of the rigid body simulator solution space but do not occupy space themselves.
* While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Editing and Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name, where such names are unique for the entire region.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims (Mantis #2966).
* Connecting a joint to the environment requires specifying one of the connected prims as "NULL", in capital letters and without quotes. "null" won't work.
* Editing one or several joints or prims in an actively simulating assembly should freeze the entire assembly, but it doesn't. (The assembly keeps simulating and moving even if a part of the assembly is selected for editing.)
* If velocity interpolate on the client is on, deactivated joint prims will sometimes fly away due to incorrectly continuation of the velocity interpolation. The server should always stop movement of joint prims when they are deactivated or renamed. Code is in place to do this, but apparently some corner cases remain unfixed.

== Linked or attached prims ==
* A linked prim cannot currently be part of a jointed assembly.
* Don't try to attach (to your avatar) prims that are part of a jointed assembly. This would however be a very cool feature in the future (allowing things like physical ponytails that swing properly), but needs more research about how to implement it.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

Development Team

2009-01-13T04:00:57Z

Nlin: /* Active OpenSim Core Developers */

== Active OpenSim Core Developers ==
These people have commit access to our central SVN server and are [http://www.ohloh.net/projects/4753/contributors regular contributors] to the codebase.

(please add in as much info as you like for your name)

<table border="1" cellpadding="2" cellspacing="0" class="sortable">
<tr>
<th>Photo </th>
<th>IRC Nick </th>
<th>Name</th>
<th>SL Avatar</th>
<th>Other Grid</th>
<th>Time Zone (UTC)</th>
<th>Org</th>
<th>Areas of Interest</th>
</tr>
<tr>
<td />
<td>[[User:MW |MW ]]</td>
<td>Darren</td>
<td>OSG:Wright Juran TN:Darren Guard</td>
<td></td>
<td>0</td>
<td>[http://tribalmedia.se/ Tribal Media AB]</td>
<td>Everything</td>
</tr>
<tr>
<td> </td>
<td>[[User:lbsa71|lbsa71]]</td>
<td>Stefan Andersson</td>
<td>Tribal Skytower</td>
<td>OSG:Stefan Andersson TN:Stefan Andersson</td>
<td>+1</td>
<td>[http://tribalmedia.se/ Tribal Media AB]</td>
<td>Web Integration</td>
</tr>
<tr>
<tr>
<td />
<td>[[User:Adam Frisby|Adam Frisby]]</td>
<td>Adam Frisby</td>
<td>Adam Zaius</td>
<td></td>
<td>+8</td>
<td>DeepThink Pty Ltd</td>
<td>Terrain, Performance</td>
</tr>
<tr>
<td />
<td>[[User:MingChen|MingChen]]</td>
<td>Mike/Michael Ortman</td>
<td>Ming Chen</td>
<td></td>
<td>-6 (-5 in Summer)</td>
<td>DeepThink Pty Ltd</td>
<td>Estate/Parcel Support/Modules/Keeping things all neat and tidy.</td>
</tr>
<tr>
<td />
<td>[[User:SeanDague|sdague]]</td>
<td>Sean Dague</td>
<td>Neas Bade</td>
<td></td>
<td>-5</td>
<td>IBM</td>
<td>Database, Linux, Testing, Misc</td>
</tr>
<tr>
<td />
<td>[[User:Tedd|Tedd]]</td>
<td>Tedd Hansen</td>
<td>Tedd Maa</td>
<td></td>
<td>+1</td>
<td>Tedd Hansen</td>
<td>Programming/Scripting/Architecture</td>
</tr>
<tr>
<td />
<td>[[User:dalien|dalien]]</td>
<td>Dalien Talbot</td>
<td>Dalien Talbot</td>
<td></td>
<td>+1</td>
<td>Mostly TCP-based</td>
<td>Small fixes; rev.eng./prototyping; nightlies; git-keeper </td>
</tr>
<tr>
<td />
<td>ckrinke</td>
<td>Charles Krinke</td>
<td>Charlesk Bing</td>
<td></td>
<td>-8</td>
<td> </td>
<td>Reliability/Grid servers/ll-functions</td>
</tr>
<tr>
<td />
<td>[[User:chi11ken|chi11ken]]</td>
<td>Jeff Ames</td>
<td>Chillken Proto</td>
<td> </td>
<td>+9</td>
<td>[http://www.3di.jp/en/ 3Di Inc, Japan] / Genkii</td>
<td> </td>
</tr>
<tr>
<td />
<td>[[User:adjohn|adjohn]]</td>
<td>Adam Johnson</td>
<td>Zeuz Zenovka</td>
<td> </td>
<td>+9</td>
<td>[http://www.3di.jp/en/ 3Di Inc, Japan] / Genkii</td>
<td> </td>
</tr>
<tr>
<td />
<td>[[User:joha1|joha1]]</td>
<td>Johan Berntsson</td>
<td>Joppi Brandenburg</td>
<td> </td>
<td>+9</td>
<td>[http://www.3di.jp/en/ 3Di Inc, Japan] http://www.3di.jp/en/</td>
<td>Performance, packet handling/libSL</td>
</tr>
<tr>
<td />
<td>[[User:Teravus|Teravus]]</td>
<td>Teravus</td>
<td>Teravus Ousley</td>
<td></td>
<td>-5</td>
<td>W3z</td>
<td>Physics & Admin tools, A working sim.</td>
</tr>
<tr>
<td />
<td>[[User:justincc|justincc]]</td>
<td>Justin Clark-Casey</td>
<td>Lulworth Beaumont</td>
<td>Justin Clark-Casey (osgrid)</td>
<td>0</td>
<td>Black Dress Technology [http://justincc.wordpress.com justincc's OpenSim blog]</td>
<td>Grid, performance & reliability, inventory (avatar and object), assets, scenes, etc.</td>
</tr>
<tr>
<td />
<td>[[Alondria]]</td>
<td></td>
<td>Alondria LeFay</td>
<td>Alondria LeFay (OSGrid)</td>
<td>-8</td>
<td>Independent</td>
<td>Implementation of LSL functions and other scripting tidbits.</td>
</tr>
<tr>
<td />
<td>[[User:DrScofield|drscofld]]</td>
<td>Dirk Husemann</td>
<td>Dr Scofield</td>
<td></td>
<td>+1</td>
<td>IBM</td>
<td>reliability, networking protocols, voice, inventory, assets, remote control, and pretty much everything else :-)</td>
</tr>
<tr>
<td />
<td>[[User:dahlia|dahlia]]</td>
<td>T. Hoff</td>
<td>Dahlia Trimble</td>
<td></td>
<td>-8 / -7</td>
<td>independent</td>
<td>prim collision geometry, more later :)</td>
</tr>
<tr>
<td></td>
<td>[[User:Mikem|mikem]]</td>
<td>Mike</td>
<td> </td>
<td> </td>
<td>+9</td>
<td>[http://www.3di.jp/en/ 3Di Inc, Japan] http://www.3di.jp/en/</td>
<td>patches, scripting improvements, LSL compiler</td>
</tr>
<tr>
<td></td>
<td>[[User:Melanie_T|Melanie_T]]</td>
<td>Melanie</td>
<td>Melanie Milland</td>
<td> </td>
<td>0</td>
<td>Xumeo Inc.</td>
<td>Scripting, Prims/Scene, Life, The Universe, and Everything</td>
</tr>
<tr>
<td></td>
<td>[[User:Homer Horwitz|Homer_Horwitz]]</td>
<td>Homer Horwitz</td>
<td>Homer Horwitz</td>
<td> </td>
<td>+2</td>
<td>Independent</td>
<td>map/TP, rev. engineering, "now, that's funny" problems, but still interested in all parts of it</td>
</tr>
<tr>
<td></td>
<td>[[User:Diva|Diva]]</td>
<td>Crista Lopes</td>
<td>Diva Canto</td>
<td>Crista Lopes / Diva Canto</td>
<td>-8</td>
<td>University of California, Irvine</td>
<td>Everything, except databases</td>
</tr>
<tr>
<td />
<td>[[User:nlin|nlin]]</td>
<td>N Lin</td>
<td>Standard Drucker</td>
<td> </td>
<td>+9</td>
<td>[http://www.3di.jp/en/ 3Di Inc, Japan] http://www.3di.jp/en/</td>
<td>Physics, scripting, more to come</td>
</tr>
</table>

== Retired OpenSim core developers ==

These people are core developers who have transcended our mortal plane (i.e. they are no longer active).

<table border="1" cellpadding="2" cellspacing="0" class="sortable">
<tr>
<th>Photo </th>
<th>IRC Nick </th>
<th>Name</th>
<th>SL Avatar</th>
<th>Other Grid</th>
<th>Time Zone (UTC)</th>
<th>Org</th>
<th>Areas of Interest</th>
</tr>
<tr>
<td />
<td>[[User:babblefrog|babblefrog]]</td>
<td>Brian McBee</td>
<td>Dogen Coldstream</td>
<td>Babblefrog Ballistic (osgrid)</td>
<td>-8</td>
<td>Disorganized</td>
<td> </td>
</tr>
<tr>
<td />
<td>[[User:danx0r|danx0r]]</td>
<td>Dan Miller</td>
<td>Albert Pascal</td>
<td></td>
<td>-8</td>
<td>squiggle.com</td>
<td>PHEEZIKS; everything</td>
</tr>
<tr>
<td />
<td>Tleiades</td>
<td> </td>
<td>Tleiades Hax</td>
<td></td>
<td>+1</td>
<td> </td>
<td>Grid servers/Database</td>
</tr>
<tr>
<td />
<td>[[User:Darok|Darok]]</td>
<td> </td>
<td>Darok Kaminski</td>
<td></td>
<td>+1</td>
<td> </td>
<td>Physics engines (especially BulletX)</td>
</tr>
<tr>
<td />
<td>Gareth / Gwen</td>
<td>Gareth Nelson</td>
<td>Gareth Ellison</td>
<td>Gareth Nelson (on everywhere but SL)</td>
<td>BST (UTC+1)</td>
<td>Litesim Ltd</td>
<td>Grid servers, sim border crossing, avatar animations</td>
</tr>
</table>

== Additional Developers/Testers/Contributors ==
These people have contributed bug reports, patches or other contributions to OpenSim.

<table border="1" cellpadding="2" cellspacing="0" class="wikitable sortable">
<tr>
<th>IRC Nick </th>
<th>Name</th>
<th>SL Avatar</th>
<th>Other Grid</th>
<th>Time Zone (UTC)</th>
<th>Org</th>
<th>Areas of Interest</th>
</tr>
<tr>
<td>[[User:Nebadon|Nebadon]]</td>
<td>Michael Cerquoni</td>
<td>Nebadon Izumi</td>
<td>Nebadon Izumi</td>
<td>-7 Arizona</td>
<td>Oni Kenkon Creations</td>
<td>Building, Scripting, Testing</td>
</tr>
<tr>
<td>[[User:jtclark48|jclark4]]</td>
<td>Jay Clark</td>
<td>Jay Clarke</td>
<td></td>
<td>-5</td>
<td>IBM</td>
<td>Physics, Grid Host, AI, Scripting, Testing</td>
</tr>
<tr>
<td>[[User:AdamStevenson|BigFootAg]]</td>
<td>Adam Stevenson</td>
<td>Adamus Petrov</td>
<td></td>
<td>-6</td>
<td>Texas A&M University</td>
<td>AI, Skynet, Evolving Systems, Biology</td>
</tr>
<tr>
<td>[[User:jeff1564|Jeff1564]]</td>
<td>Jeff</td>
<td>Potter Taurog</td>
<td></td>
<td>-8</td>
<td></td>
<td>Building, Scripting, Testing</td>
</tr>
<tr>
<td>Rock_Vacirca</td>
<td>Colin Withers</td>
<td>Rock Vacirca</td>
<td> </td>
<td>+1</td>
<td>http://rock-vacirca.blogspot.com</td>
<td>Testing, building, scripting, maintaining an opensim blog.</td>
</tr>
<tr>
<td>simsim</td>
<td>caocao</td>
<td> </td>
<td> </td>
<td>+9</td>
<td> </td>
<td>Testing whole functions of OpenSim system,working with OpenSim-Engine,reporting on OpenSim</td>
</tr>

<tr>
<td>[[User:Vicero Lambert|Vicero Lambert]]</td>
<td> </td>
<td> </td>
<td></td>
<td> </td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>Ldvoipeng</td>
<td> </td>
<td> </td>
<td></td>
<td> </td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>idoru</td>
<td> </td>
<td> </td>
<td></td>
<td> </td>
<td> </td>
<td> </td>
</tr>
<tr>
<td>[[User:Magi|Magi]]</td>
<td>Andy Agnew</td>
<td>Magi Merlin</td>
<td></td>
<td>+10</td>
<td>Spun Pty Ltd</td>
<td>3D Web Integration, Database stuff and playing with the odds and ends box.</td>
</tr>
<tr>
<td>john_</td>
<td>John Moyer</td>
<td>VAJohn GeekSquad or Matthew Kendal</td>
<td></td>
<td>-5</td>
<td>Best Buy/Geek Squad</td>
<td>Tester</td>
</tr>
<tr>
<td>[[User:ClarkZone|ClarkZone]]</td>
<td>Troy Admin(@ClarkZone)</td>
<td>Troy Childs</td>
<td>Troy Admin (ClarkZone)</td>
<td>-5</td>
<td>Http://clarkzone.dyndns.org</td>
<td>Tester and Grid Host</td>
</tr>
<tr>
<td>[[User:aiaustin|aiaustin]]</td>
<td>Ai Austin</td>
<td>Ai Austin</td>
<td>Ai AIAI (AIAI Grid)</td>
<td>+0</td>
<td>AIAI, University of Edinburgh http://www.aiai.ed.ac.uk/~ai/ http://vue.ed.ac.uk/openvue/</td>
<td>Windows Vista tests Content testing Use of multiple VWs</td>
</tr>
<tr>
<td>Marc Manders</td>
<td>Marc Manders</td>
<td> </td>
<td> </td>
<td>+6</td>
<td>marcmanders@gmail.com</td>
<td>creative features</td>
</tr>
<tr>
<td>[[User:balthazar|balthazar]]</td>
<td>Trevor Brooks</td>
<td>Balthazar Sin</td>
<td></td>
<td>-5</td>
<td>None</td>
<td>Terrains, testing and some small coding tasks</td>
</tr>
<tr>
<td>[[User:jimbo2120|jimbo2120]]</td>
<td>Michael Osias</td>
<td>Illuminous Beltran</td>
<td></td>
<td>-5</td>
<td>IBM</td>
<td>Grid, AI, Skynet, coding and testing</td>
</tr>
<tr>
<td>[[User:Sakai|Sakai]]</td>
<td>Steve S</td>
<td></td>
<td>Sakai Openlife (OpenlifeGrid)</td>
<td>+10</td>
<td>http://www.openlifegrid.com</td>
<td>Grid, Hardware, Testing, Contribution</td>
</tr>
<tr>
<td>ZeroPoint</td>
<td> </td>
<td>Guilderoy Dench</td>
<td></td>
<td>-5</td>
<td> </td>
<td>Programming/Database</td>
</tr>
<tr>
<td>MaltosSosa</td>
<td>Maltos Sosa</td>
<td>Maltos Sosa </td>
<td>Maltos Sosa (Central Grid)</td>
<td> </td>
<td>Central Grid</td>
<td>Grid Operator, Central Grid Project Manager. Anything we can offer, just ask.</td>
</tr>

<tr>
<td>[[User:DerekTang|DerekTang]]</td>
<td>Derek Tang</td>
<td>Derek Timeless</td>
<td>Derek Tang (ChineseGrid)</td>
<td>+8</td>
<td>http://ChineseGrid.net</td>
<td>Running a public WINDOWS sim for testing, Docs, Helping Chinese users to enjoy OpenSim; building Chinese OpenSim communities. In construction...</td>
</tr>

<tr>
<td>[[User:TayB|TayB]]</td>
<td>Earl B</td>
<td>Taylor Boyau</td>
<td></td>
<td>-10</td>
<td>ViziGrid</td>
<td>Grid Host,Networking,Contributions & Testing.</td>
</tr>
<tr>
<td>[[User:JamieDav|JamieDav]]</td>
<td>Jamie David</td>
<td>Jamie David</td>
<td></td>
<td>+7</td>
<td>Forum</td>
<td>Grid, Sim, Avitar, Functionality</td>
</tr>
<tr>
<td>[[User:Krtaylor|Krtaylor]]</td>
<td>Kurt Taylor</td>
<td>Kurt Stringer </td>
<td></td>
<td>-6</td>
<td>IBM</td>
<td>Grid, Networking, Monitoring, Scripting, Inventory, Testing</td>
</tr>
<tr>
<td>[[User:Nink|Nink]]</td>
<td>Peter Finn</td>
<td>Nink Noonan</td>
<td></td>
<td>-5</td>
<td>IBM</td>
<td>Disruptive Influence.</td>
</tr>
<tr>
<td>[[User:Bruce|Bruce]]</td>
<td>Bruce Meerson</td>
<td>Bruce Meerson</td>
<td></td>
<td>+8</td>
<td>HiPiHi</td>
<td>Watching.</td>
</tr>
<tr>
<tr>
<td>[[User:Darb|DarbD]]</td>
<td>Brian B. Quinn</td>
<td>Darb Dabney</td>
<td>regions near Berkeley</td>
<td>-7</td>
<td>City of Berkeley, CA http://blog.simgis.org</td>
<td>LiDAR-based sculpties, real-world terrain, pursuit of civic paraverses </td>
</tr>
<tr>
<td>[[CharlieO]]</td>
<td>Dan</td>
<td>Charlie Omega</td>
<td></td>
<td> </td>
<td> </td>
<td>Mild coding/tweaking/simple feature adds, Stress testing/break stuff, Testing limits of existing code. Making sure [[LSL Status]] is up to date</td>
</tr>
<tr>
<td>oobscure</td>
<td> </td>
<td>Opensource Obscure</td>
<td></td>
<td>+1</td>
<td>http://www.opensim.it</td>
<td>Running a public Linux sim for testing, Docs, Helping italian users, Building opensim communities, Watching</td>
</tr>
<tr>
<td>pitman</td>
<td>Mike Pitman</td>
<td>Rez Tone</td>
<td></td>
<td> </td>
<td>IBM</td>
<td>Scientific visualization schemes, virt world product design, persistant workspaces, virt world based big biz</td>
</tr>
<tr>
<td>cmu</td>
<td>Christopher Mumme</td>
<td>Snook Destiny</td>
<td></td>
<td>+1</td>
<td>http://www.cmu-develop.de/ and research group "Collaboration Systems and CSCW" at Clausthal University of Technology</td>
<td>Testing OpenSim, working with OpenSim-Engine, reporting on OpenSim</td>
</tr>

<tr>
<td>[[Silpol]]</td>
<td>Andriy Tymchenko</td>
<td>Andy Tir</td>
<td></td>
<td>EET (+2/3)</td>
<td> http://silpol.blogspot.com/ (also visible at Nokia)</td>
<td>highly uncoordinated mess with elements of palace games, under-table diplomacy, rebellion, coup d'état and mutiny. optionally pirate</td>
</tr>
<tr>
<td>[[User:Grumly|Grumly]]</td>
<td></td>
<td>Forest Klaar</td>
<td>Grumly TheBear</td>
<td>GMT+1</td>
<td>.NET MCAD Dev/Arch/Trainer http://www.devoteam.com</td>
<td>Trying to get into OpenSim code for now. Particularly interrested in data persistence. blog (Hello, Avatar!): http://lslblog.free.fr</td>
</tr>
<tr>
<td>[[daTwitch]]</td>
<td>James G. Stallings II</td>
<td> Lazarus Longstaff</td>
<td>Hiro Protagonist (OSGrid)</td>
<td>-5</td>
<td>House Husband</td>
<td>OSGrid Region owner, OSGrid Operator, Forum Admin, sometime wiki editor</td>
</tr>

<tr>
<td>gryc</td>
<td>Gryc Ueusp</td>
<td>Gryc Uriza</td>
<td>Gryc Uriza(OSGrid)</td>
<td>-6</td>
<td></td>
<td>PHP scripting, web interfaces, interconnectivity, cross-platformedness</td>
</tr>

<tr>
<td>[[User:Phrearch|Phrearch]]</td>
<td>Jeroen van Veen</td>
<td>Phrearch Miles</td>
<td>Phrearch Miles(OSGrid)</td>
<td>Amsterdam/Paris</td>
<td></td>
<td>WiXTD, Wikidoc and Moo</td>
</tr>

<tr>
<td>[[User:Burnman|Burnman]]</td>
<td>Allen Wilkins</td>
<td>Burnman Bedlam</td>
<td>Sid Green (United Grid)</td>
<td>Boston, USA</td>
<td>United Grid</td>
<td>Testing, testing, and more testing! Getting familiar with the source, interested in all aspects of the project.</td>
</tr>

<tr>
<td>[[User:krisbfunk|krisbfunk]]</td>
<td>Kris Bulman</td>
<td>krisbfunk Vought</td>
<td>Krisbfunk Nocturnal(OSGrid)</td>
<td>PE, Canada (-4)</td>
<td>Edactive Technologies NocturnalEye Productions UPEI</td>
<td>Currently: Testing, bug reports, wiki updating, building on OSGrid</td>
</tr>

<tr>
<td>[[User:HashBox|HashBox]]</td>
<td> </td>
<td>Sibariel Darkstone</td>
<td>Sibariel Darkstone (OSGrid)</td>
<td>New Zealand (+12)</td>
<td></td>
<td>Testing, bug reports, and updating the wiki.</td>
</tr>

<tr>
<td>[[User:Kinoc|Kinoc]]</td>
<td>Kino Coursey</td>
<td>Daxxon Jaxxon</td>
<td>Daxxon Kinoc (OSgrid)</td>
<td>-6</td>
<td>Daxtron Laboratories http://www.daxtron.com University of North Texas</td>
<td>AI, Semantic web, Ontologies, Natural Laanguage Processing, Cyc, Bots, NPC </td>
</tr>
<tr>
<td>[[User:trapuh|trapuh]]</td>
<td>Pedro Ribeiro</td>
<td>Vaiten Forder</td>
<td></td>
<td>GMT</td>
<td>University Student, Escola Superior de Educação de Viseu, Portugal </td>
<td>Testing, eventual bug reports and wiki. Music, web/digital arts and php+sql.</td>
</tr>
<tr>
<td>[[User:SonicViz|SonicViz]]</td>
<td>Paul Cohen</td>
<td>Komuso Tokugawa</td>
<td></td>
<td>+9</td>
<td>Http://sonicviz.com</td>
<td>Audio/Music, Interactive Music, Control Protocols, Interfaces, VisualFX, Procedural animation/Generative systems + testing and general dev</td>
</tr>
<tr>
<td>[[User:Mokele|mokele]]</td>
<td>Scott Norman</td>
<td>Mokelembembe Mokeev</td>
<td></td>
<td>-8 (Southern California)</td>
<td>Web Developer (PHP and MySQL)</td>
<td>Interested in seeing running on PowerPC Macs which it is. So, when I can, I'll compile and test on PowerPC Mac (PowerBook G4) and submit reports and then update the wiki if need on installing on Mac. Also have a Ubuntu 7.10 server that I can do testing on too.</td>
</tr>

<tr>
<td>[[User:devalnor|devalnor]]</td>
<td>Devalnor</td>
<td>M. Watkin</td>
<td></td>
<td>+1 (Belgium)</td>
<td></td>
<td>Small Patch code, bug reports, and updating the wiki.</td>
</tr>

<tr>
<td>[[User:Ezekiel|Ezekiel]]</td>
<td>Ezekiel</td>
<td>Ezekiel Zabelin</td>
<td></td>
<td>+1 </td>
<td>http://www.yosims.com </td>
<td>Concepts, business aspects of virtual worlds - web developer (PHP, MySQL, Javascript, LSL) </td>
</tr>

<tr>
<td>[[User:Buggmaster|Buggmaster]]</td>
<td>Mike D</td>
<td>Bug Master</td>
<td>None</td>
<td>-8 </td>
<td>http://www.adultmetaverse.com</td>
<td>Grid, Data/Web PHP/PERL/MySQL</td>
</tr>

<tr>
<td>[[User:Nixnerd|nixnerd]]</td>
<td>Richmund</td>
<td>Dangerously Moody</td>
<td>None</td>
<td>GMT </td>
<td>http://www.integratedtechnologies.eu</td>
<td>Cross Platform Testing, Feedback, Bug Reporting</td>
</tr>

<tr>
<td>[[User:MoHax|mohax]]</td>
<td>Mo Hax</td>
<td>Mo Hax</td>
<td></td>
<td>-5 Eastern</td>
<td>IBM</td>
<td>Testing, Feedback, Content Contributions, Bug Reporting, Documenting, Development</td>
</tr>

<tr>
<td>[[User:Webmage|webmage]]</td>
<td>webmage</td>
<td>Leyla Masala</td>
<td>Web Mage</td>
<td>+1</td>
<td>IBM</td>
<td>Testing, terrain</td>
</tr>

<tr>
<td>[[User:NLStitch|NLStitch]]</td>
<td>Marijn Oosterveld</td>
<td>Stitch Seale</td>
<td>NYA</td>
<td>GMT +1 Amsterdam</td>
<td>Twingate Systems (http://www.twingate.nl) HanzeHogeschool Groningen, Netherlands
</td>
<td>Programming, Photography, AI</td>
</tr>

<tr>
<td>[[User:Ideia Boa|Ideia Boa]]</td>
<td>Joao Lopes</td>
<td>Ideia Boa</td>
<td>Ideia Boa or Boa Ideia in some grids</td>
<td>GTM+1 Stockholm/Sweden</td>
<td>Cub SL Portugues - Portugueses Virtual World Site http://www.clubslportugues.com OpenSimPT the Grid for Portuguese language too http://www.opensimpt.com</td>
<td>Testing and more testing! Trying to get into OpenSim code for now. Updating the original wiki and translating the OpenSim Wiki into Portuguese and reporting on OpenSim</td>
</tr>

<tr>
<td>[[User:Lulurun|lulurun]]</td>
<td>liu</td>
<td> </td>
<td> </td>
<td>+9</td>
<td>3Di Inc, Japan http://www.3di.jp</td>
<td>patches, openid, server performance, UGAI</td>
</tr>

<tr>
<td>[[User:Carlosroundel|Carlosrounde]]</td>
<td>Carlosroundel</td>
<td>Carlos Roundel</td>
<td> </td>
<td>+1</td>
<td>Cyberlandia Italy http://www.cyberlandia.net</td>
<td>grid, programmer, database, tester</td>
</tr>

<tr>
<td>[[User:Mikebert|Mikebert]]</td>
<td>Michael Strunck</td>
<td>Mikebert Miles</td>
<td> </td>
<td>+1</td>
<td>OpenSIM Wiki, Germany http://www.opensim.de</td>
<td>German Wiki, Translater, Server Performance (Linux/Windows), Tester, Feedback, Bug Reporting, Server-Hosting</td>
</tr>

<tr>
<td>[[User:Fly-man-|Fly-Man-]]</td>
<td>Laurence</td>
<td></td>
<td>Fly Man</td>
<td>+1</td>
<td></td>
<td>Testing, OpenSimSearch, OpenSimProfile, OpenWiredux</td>
</tr>

<tr>
<td>Taoki</td>
<td>Mircea Kitsune / Taoki Vixen</td>
<td>Mircea Kitsune (OSGrid) / Mircea Lobo (LL grid)</td>
<td> </td>
<td>GMT +2</td>
<td> </td>
<td>Usually testing and bug reporting but I also make smaller patches where I know what to do.</td>
</tr>

<tr>
<td>[[User:Patnad|Patnad]]</td>
<td>Patrick</td>
<td>Patnad Babii</td>
<td>Patnad Babii (OSGrid)</td>
<td>GMT -5</td>
<td> </td>
<td>Bug testing and reporting, I code C# but haven't touched OpenSim Project.. Yet!</td>
</tr>

<tr>
<td>[[User:Hallow Palmer|Hallow Palmer]]</td>
<td>Markus</td>
<td>Hallow Palmer</td>
<td> </td>
<td>+1</td>
<td>Grid4Us http://www.grid4us.net</td>
<td>Server Performance (Windows), Tester, Feedback, Business concepts,Bug Reporting, Server-Hosting</td>
</tr>
<tr>
<td>[[User:^DarkMan|^DarkMan]]</td>
<td>Brian Adair</td>
<td>Patrick Ouachita</td>
<td>Brian Adair | Patrick Meta</td>
<td>-6 CST</td>
<td>RealMetaLife | B&H Networking</td>
<td>Building, Scripting, Testing, etc.</td>
</tr>
</table>
[[Category:Main]]
[[Category:Development]]

NINJA Physics

2009-01-13T03:42:24Z

Nlin: /* Tips for effectively using joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Separate from NINJA Physics, other activity has recently accelerated on LSL script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object, also called a joint prim, is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the affected prims' movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate. A joint prim only affects the physics simulation if the joint prim's "[x] Physical" property is activated.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint prim.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. Technically, joints are implemented in the physics engine as mathematical (equality or inequality) constraints on the position and/or velocity of rigid bodies, so they constrain the admissible region of the rigid body simulator solution space but do not occupy space themselves.
* While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Editing and Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name, where such names are unique for the entire region.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims (Mantis #2966).
* Connecting a joint to the environment requires specifying one of the connected prims as "NULL", in capital letters and without quotes. "null" won't work.
* Editing one or several joints or prims in an actively simulating assembly should freeze the entire assembly, but it doesn't. (The assembly keeps simulating and moving even if a part of the assembly is selected for editing.)

== Linked or attached prims ==
* A linked prim cannot currently be part of a jointed assembly.
* Don't try to attach (to your avatar) prims that are part of a jointed assembly. This would however be a very cool feature in the future (allowing things like physical ponytails that swing properly), but needs more research about how to implement it.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2009-01-13T03:19:57Z

Nlin: /* Editing and Naming limitations */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Separate from NINJA Physics, other activity has recently accelerated on LSL script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object, also called a joint prim, is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the affected prims' movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate. A joint prim only affects the physics simulation if the joint prim's "[x] Physical" property is activated.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint prim.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Editing and Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name, where such names are unique for the entire region.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims (Mantis #2966).
* Connecting a joint to the environment requires specifying one of the connected prims as "NULL", in capital letters and without quotes. "null" won't work.
* Editing one or several joints or prims in an actively simulating assembly should freeze the entire assembly, but it doesn't. (The assembly keeps simulating and moving even if a part of the assembly is selected for editing.)

== Linked or attached prims ==
* A linked prim cannot currently be part of a jointed assembly.
* Don't try to attach (to your avatar) prims that are part of a jointed assembly. This would however be a very cool feature in the future (allowing things like physical ponytails that swing properly), but needs more research about how to implement it.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2009-01-12T12:05:54Z

Nlin: /* Definitions */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Separate from NINJA Physics, other activity has recently accelerated on LSL script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object, also called a joint prim, is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the affected prims' movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate. A joint prim only affects the physics simulation if the joint prim's "[x] Physical" property is activated.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint prim.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Editing and Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name, where such names are unique for the entire region.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims (Mantis #2966).
* Editing one or several joints or prims in an actively simulating assembly should freeze the entire assembly, but it doesn't. (The assembly keeps simulating and moving even if a part of the assembly is selected for editing.)

== Linked or attached prims ==
* A linked prim cannot currently be part of a jointed assembly.
* Don't try to attach (to your avatar) prims that are part of a jointed assembly. This would however be a very cool feature in the future (allowing things like physical ponytails that swing properly), but needs more research about how to implement it.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2009-01-12T11:55:50Z

Nlin: /* Editing and Naming limitations */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Separate from NINJA Physics, other activity has recently accelerated on LSL script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Editing and Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name, where such names are unique for the entire region.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims (Mantis #2966).
* Editing one or several joints or prims in an actively simulating assembly should freeze the entire assembly, but it doesn't. (The assembly keeps simulating and moving even if a part of the assembly is selected for editing.)

== Linked or attached prims ==
* A linked prim cannot currently be part of a jointed assembly.
* Don't try to attach (to your avatar) prims that are part of a jointed assembly. This would however be a very cool feature in the future (allowing things like physical ponytails that swing properly), but needs more research about how to implement it.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2009-01-12T11:54:13Z

Nlin: /* Naming limitations */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Separate from NINJA Physics, other activity has recently accelerated on LSL script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Editing and Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name, where such names are unique for the entire region.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims (Mantis #).
* Editing one or several joints or prims in an actively simulating assembly should freeze the entire assembly, but it doesn't. (The assembly keeps simulating and moving even if a part of the assembly is selected for editing.)

== Linked or attached prims ==
* A linked prim cannot currently be part of a jointed assembly.
* Don't try to attach (to your avatar) prims that are part of a jointed assembly. This would however be a very cool feature in the future (allowing things like physical ponytails that swing properly), but needs more research about how to implement it.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2009-01-08T08:25:04Z

Nlin: /* Linked or attached prims */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Separate from NINJA Physics, other activity has recently accelerated on LSL script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked or attached prims ==
* A linked prim cannot currently be part of a jointed assembly.
* Don't try to attach (to your avatar) prims that are part of a jointed assembly. This would however be a very cool feature in the future (allowing things like physical ponytails that swing properly), but needs more research about how to implement it.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2009-01-08T08:24:18Z

Nlin: attached jointed assemblies

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Separate from NINJA Physics, other activity has recently accelerated on LSL script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked or attached prims ==
* A linked prim cannot currently be part of a jointed assembly.
* Don't try to attach (to your avatar) prims that are part of a jointed assembly. This would however be a very cool feature in the future, but needs more research about how to implement it.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-29T13:10:10Z

Nlin: /* Troubleshooting */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Separate from NINJA Physics, other activity has recently accelerated on LSL script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-29T00:58:48Z

Nlin: /* NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Separate from NINJA Physics, other activity has recently accelerated on LSL script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoiint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-28T17:17:42Z

Nlin: /* NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.

= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoiint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-28T14:13:26Z

Nlin: /* Quick start */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available. Important note if NINJA Physics is not working for you: The NINJA Physics in SVN r7875 should work but requires C# 3.0. The NINJA Physics in r7878 does not work. If you use SVN r7878 or above, please apply the additional patch in Mantis #2928 at http://opensimulator.org/mantis/view.php?id=2928
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoiint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-28T03:59:34Z

Nlin: /* Tips for effectively using joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoiint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. While the joint proxy is active (physical), you cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T18:17:51Z

Nlin: /* Tips for effectively using joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoiint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction, collision bounce, and collision filtering settings in OpenSim.ini can be tweaked for different effects.
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T18:14:06Z

Nlin: /* Tips for effectively using joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoiint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==

* The joint proxy object itself does not collide with anything and has no geometric representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T18:12:12Z

Nlin: /* Troubleshooting */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

* Joint error messages displayed in-world like script compiler errors. If, for example, you create a hinge joint (by naming a prim "hingejoiint-uniquename") but specify non-existent or non-physical body names in the Description field, the joint will not be able to be created and a warning icon appears in-world on top of the joint. Click on the warning icon to see the error message. Deactivate, correct, and re-activate the joint.
* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object. You should only change the name when the joint is deactivated.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected. You should only change the name when the prim is deactivated.

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T14:25:55Z

Nlin: /* Part 5: ODE joints implementation */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of prim taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T14:22:46Z

Nlin: /* Part 5: ODE joints implementation */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has been re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T14:17:03Z

Nlin: /* Activating and deactivating bodies and joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object causes deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has bee re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T13:24:11Z

Nlin: /* Tips for effectively using joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has bee re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T11:48:38Z

Nlin: /* Tips for effectively using joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joints don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has bee re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T11:31:24Z

Nlin: /* Activating and deactivating bodies and joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joint's don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has bee re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T11:29:02Z

Nlin: /* Multi-user testing */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

, especially == Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joint's don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has bee re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Client-side issues ==
The client has no knowledge of joints and renders each prim separately. It is possible that network lags will lead to temporary visual breakage of the joints on the client because the jointed prims' positions/orientations/velocities are updated separately without consideration of the joints.

== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T11:20:12Z

Nlin: /* Part 5: ODE joints implementation */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

, especially == Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joint's don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge. In v2 of the patch (included in trunk) the optimization - which is actually a throttle that is necessary - has bee re-instated, additionally adding a check for rotational-only motion to allow rotation updates to be transmitted even in the absence of translational motion.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T11:17:34Z

Nlin: /* Part 3: scene */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

, especially == Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joint's don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

In v2 of this patch (now included in trunk), the joint callback handlers have been moved into Scene.cs.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T11:12:20Z

Nlin: /* Quick start */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# <s>Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874</s> I am happy to report that NINJA Physics is included in trunk SVN as of r7875, so update your repository and it should be available.
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

, especially == Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joint's don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T11:02:02Z

Nlin: /* Tips for effectively using joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

, especially == Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joint's don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T11:01:12Z

Nlin: /* Troubleshooting */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

, especially == Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems. If you keep getting errors with a joint, it is possible that some other prim somewhere in the region has the same name. Try changing the name of the joint proxy object.
* Duplicate prim names cause problems. If you are repeatedly unable to connect a prim with a joint, it is possible that some other prim somewhere in the region has the same name, and that the joint is connecting to that prim instead of the one you want. Try changing the name of the prim being connected.
* Joint error messages displayed in-world like script compiler errors

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joint's don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T10:56:35Z

Nlin: /* Tips for effectively using joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems
* Duplicate prim names cause problems
* Joint error messages displayed in-world like script compiler errors
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez. Do not rez the same jointed assembly more than once or you will have prims and joints with duplicate names, which causes unexpected behavior as the joint's don't know which of the duplicated prims they are supposed to connect.
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T10:54:26Z

Nlin: /* Persistence of joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems
* Duplicate prim names cause problems
* Joint error messages displayed in-world like script compiler errors
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* All jointed assemblies in the region should be deactivated before shutting down the region. Upon region restart, select and re-activate the jointed assemblies. However, this leads to gradual accumulation of joint error (see below).
* "Live" jointed assemblies are not properly restored on region shutdown/startup. In other words, if you activate a jointed assembly then, while the jointed assembly is still simulating, shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup. This is a bug and will hopefully soon be fixed. Additionally, accumulation of joint error still occurs (see below).
* A region with deactivated jointed assemblies can be saved/loaded with save-oar/load-oar. However, trying to use save-oar/load-oar with live jointed assemblies that are actively simulating doesn't work due to threading/atomicity issues (see below).

To summarize:
* Deactivate jointed assemblies before persisting them.
* Expect gradual accumulation of joint error over time (see below).
* Periodically delete and re-rez the jointed assembly from inventory to correct joint error.

== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T10:44:04Z

Nlin: /* Tips for effectively using joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems
* Duplicate prim names cause problems
* Joint error messages displayed in-world like script compiler errors
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint proxy (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* Prims connected by joiints should probably be simple shapes like boxes or spheres for simpler collision. Complex shapes with twists or cuts cause creation of concave meshes with sharp corners which may not collide smoothly (leading to jitter) or quickly. Unfortunately, it doesn't seem possible to use ODE capsules (often used for ragdoll limbs) for collision detection because there is no way to specify a "capsule" geometry for a prim in the viewer.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T10:23:12Z

Nlin: /* Naming limitations */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems
* Duplicate prim names cause problems
* Joint error messages displayed in-world like script compiler errors
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Linked prims ==
* A linked prim cannot currently be part of a jointed assembly.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T03:46:16Z

Nlin: /* Tips for effectively using joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems
* Duplicate prim names cause problems
* Joint error messages displayed in-world like script compiler errors
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top each other and on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T03:43:26Z

Nlin: /* Troubleshooting */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems
* Duplicate prim names cause problems
* Joint error messages displayed in-world like script compiler errors
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

== Tips for effectively using joints ==
(work in progress...)

* The joint proxy object itself does not collide with anything and has no representation in the physics scene. You cannot directly physically manipulate the joint (by dragging it in the viewer or through script physics). When active, its position always automatically follows the position of the jointed bodies.
* Prims connected by a joint do not collide with each other.
* Prims connected by a joint can overlap on top of the joint proxy object, effectively hiding the joint proxy object.
* You can also make the joint proxy object very small or transparent to hide it.
* If you hide the joint proxy, it can be difficult to debug when things go wrong. Hide joints only after you've verified that the joints are created properly.
* To take a jointed assembly into inventory:
** Select all
** Deactivate
** Link
** Take
* To rez a jointed assembly from inventory:
** Rez
** Move to desired location
** Unlink
** Select all
** Activate
* Friction settings in OpenSim.ini can be tweaked for different effects

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T03:33:15Z

Nlin: /* Things that can go wrong */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Troubleshooting ==

(work in progress...)

* Duplicate joint names cause problems
* Duplicate prim names cause problems
* Joint error messages displayed in-world like script compiler errors
* Workflow for creating a complex jointed assembly
** Create a few prims
** Create a few joints
** Select them all
** Keeping the selection, click "[x] Physical" to turn on physics
** Keeping the selection, observe if joint error message icons appear
** Keeping the selection, cllick "[ ] Physical" to turn off physics
** Fix any joint error messages that occured (e.g. mistyped or duplicate prim names)
** Repeat
** When all joint error messages are fixed for the group of prims under consideration, continue to construct more of the assembly

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T03:26:04Z

Nlin: /* Noisy logging */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Things that can go wrong ==

(work in progress...)

* Duplicate joint names cause problems
* Duplicate prim names cause problems

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-27T03:22:59Z

Nlin: /* Activating and deactivating bodies and joints */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

== Things that can go wrong ==

(work in progress...)

* Duplicate joint names cause problems
* Duplicate prim names cause problems

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.
== Noisy logging ==
The current logging output contains too many debugging messages and should be reduced.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-19T15:01:28Z

Nlin: /* Quick start */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/download/frsrelease/142/304/demo-playground.tgz
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.
== Noisy logging ==
The current logging output contains too many debugging messages and should be reduced.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-19T11:38:24Z

Nlin:

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/project/ninjaphysics/scmsvn/?action=browse&path=%2F%2Acheckout%2A%2Ftrunk%2Fdata%2Fdemo-playground.tgz&revision=2
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.
== Noisy logging ==
The current logging output contains too many debugging messages and should be reduced.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.
= Links =
* GForge project homepage http://forge.opensimulator.org/gf/project/ninjaphysics/

NINJA Physics

2008-12-19T11:32:36Z

Nlin: /* Philosophy */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/project/ninjaphysics/scmsvn/?action=browse&path=%2F%2Acheckout%2A%2Ftrunk%2Fdata%2Fdemo-playground.tgz&revision=2
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.
== Noisy logging ==
The current logging output contains too many debugging messages and should be reduced.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

NINJA Physics

2008-12-19T11:31:32Z

Nlin: /* Definitions */

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by using repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/project/ninjaphysics/scmsvn/?action=browse&path=%2F%2Acheckout%2A%2Ftrunk%2Fdata%2Fdemo-playground.tgz&revision=2
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is initially specified by and later visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.
== Noisy logging ==
The current logging output contains too many debugging messages and should be reduced.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

NINJA Physics

2008-12-19T11:25:55Z

Nlin:

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =
This project proposes a new physics extension called NINJA Physics. The NINJA Physics extension enhances the ODE physics in OpenSim with joints: movable linkages between prims. This will allow wheeled vehicles, ragdolls, and mechanical/robotic assemblies to be interactively built within the standard viewer and controllable through scripting. This kind of physics is not currently available in OpenSim or Second Life.

A demonstration of the idea can be seen here: http://jp.youtube.com/watch?v=nirTXPO-opE

NINJA stands for a Networked INteractive Jointed Assembly. "Jointed Assembly" refers to an articulated rigid body. The "INteractive" aspect refers to interactive editing in 3D space of jointed assemblies using the viewer and intuitive 3D placement of joint objects as normal prims. The "Networked" aspect refers to many users simultaneously interacting with jointed assemblies in a networked virtual world.

The core ODE physics engine already provides support for joints; it is OpenSim and the viewer that lack support. This project therefore aims to extend the OpenSim physics interface to access the ODE joint functionality. Furthermore, this project must also provide a means of creating and editing joints within the standard viewer, which has no native support for joints. In the future, viewer changes and protocol changes can be considered for native joint support.

This new kind of physics, jointed physics, is separate from and complementary to the existing LSL script-based vehicles. Activity has recently accelerated on script-based vehicles, with some water-based vehicles already working (e.g. sailboats). The new jointed/NINJA physics will allow more new kinds of vehicles not currently possible with scripting. Two example of new kinds of vehicles are cars with wheels that actually turn and rotate, and robots that walk by moving limbs.
= Philosophy =
The development of NINJA Physics follows these principles.

# Break nothing. When turned off, NINJA Physics should have no observable effect on simulator behavior. When turned on, existing physics behavior without joints should be exactly the same as before. Additionally, new physics behavior with joints should be available to the user.
# Standard viewer compatibility. Editing of joints must be possible using only the affordances of the standard viewer. This means we must enter new information (joint information) in an existing GUI not designed for that purpose. We do this by using repurposing existing prim editor fields (Name and Description) and using a special naming convention to specify joints. The requirment of standard viewer compatibility conflicts slightly with the requirement of breaking nothing; by using a special naming convention, it is possible that existing regions might already use that naming convention, which would lead to altered behavior. In practice, this will likely not be a great concern.
# Code readability. The first version of the NINJA Physics patch is implemented in as straightforward a way as possible to allow understanding and critique of the basic approach. At this stage, no overly-clever optimizations and only necessary abstractions have been applied.
# Generalizability. The first version of NINJA Physics is implemented using ODE Physics, but the same implementation should be usable for any physics engine that supports joints.

= User documentation =
== Quick start ==
To try out NINJA Physics, follow these steps.
# Apply the patch ninja-allparts.patch to your OpenSim source tree and compile. Available at http://opensimulator.org/mantis/view.php?id=2874
# Copy demo-playground.tgz to your opensim/bin directory. Available at http://forge.opensimulator.org/gf/project/ninjaphysics/scmsvn/?action=browse&path=%2F%2Acheckout%2A%2Ftrunk%2Fdata%2Fdemo-playground.tgz&revision=2
# Edit OpenSim.ini to run in standalone mode with ODE physics. Set use_NINJA_physics_joints=true.
# Start OpenSim.exe. In the region console type load-oar demo-playground.tgz to load demo data.
# Login to the region and navigate to (128,128). Select all prims in the swing object (Ctrl+3, mouse drag). If you have a powerful CPU, you can also select everything in the region, but note that processing joints takes some CPU power, so you may want to select a smaller group of objects to start.
# In the object editing window, click on the "Physical" checkbox in the "Object" tab to turn the selection physical, then press ESC to exit selection mode. The prims and the joints go "live".
# Click on the jointed assembly and drag it around. Also, the following commands spoken in chat can control the ragdoll: "arise", "kneel", "die".

== Definitions ==

A joint is a constraint on the motion of rigid bodies. Currently we consider two types of joints: a ball-and-socket joint and a hinge joint. A ball-and-socket joint is similar to the joint connecting your upper arm to your shoulder; the joint constrains the position of the two bodies, but allows free rotation. A hinge joint is similar to a door hinge: it constrains the position of two bodies but allows rotation about only one axis, the hinge axis. By using joints, we can create complex assemblies of prims in OpenSim that move with realistically-constrained motion.

A joint proxy object is a prim created in the viewer and existing within the region to represent a joint. Its position, relative to the prims it affects, defines the position around which the prims movement will be constrained. For hinge joints, the orientation of the joint proxy object defines the hinge axis; specifically, the x-axis of the proxy object is defined as the axis about which the connected prims will be allowed to rotate.

A physics engine joint is the data structure within the physics engine that actually constrains the behavior of the rigid bodies as simulated in the simulator. The physics engine joint is visualized by the joint proxy object.

== Enabling NINJA Physics in OpenSim.ini ==

In OpenSim.ini, set "physics = OpenDynamicsEngine" and "use_NINJA_physics_joints = true".

== Creating a ball-and-socket joint ==

Create two box prims side-by-side with space in between them. Leave them non-physical for now. Give each one a unique name (right click, edit, General tab, Name). Example names are "box1" and "box2". Leave the dimensions at (0.5, 0.5, 0.5). These 2 prims will be connected by a ball joint.

Create a small sphere. Make its dimensions something like (0.1, 0.1, 0.1). This prim represents a ball-and-socket joint. Position the sphere between the 2 boxes. Assign the small sphere the name of "balljoint-uniquename", where "uniquename" is a unique name not used by any other prim. Give the sphere a Description of "box1 box2", which are the names of the 2 prims to be connected, separated by a space.

Close all windows in the viewer. Press Ctrl+3 to enter edit mode. Drag the mouse to highlight the 2 boxes to be connected and the small sphere.

In the object editing window, click on the "Physical" checkbox in the "Object" tab.

Drag the boxes around and notice they remain connected by a joint.

== Creating a hinge joint ==

A similar procedure is used for creating bodies connected with hinge joints, with the following differces:

The joint object should be named "hingejoint-uniquename", where uniquename is a unique name not used elsewhere in the region.

The joint object's position determines the anchor of the hinge.

The joint object's X axis orientation determines the axis of rotation of the hinge. The easiest way to visualize this is to create a prim whose size is elongated along its x axis; set the object size directly in the object editor to something like (1.0, 0.1, 0.1).

Hinges can be used for simulating wheels. Connected bodies can rotate freely around the hinge, like a wheel around an axle.

== Activating and deactivating bodies and joints ==

Setting a joint proxy object to "physical" causes creation of that joint in the physics engine. Setting the joint proxy object to non-physical, or deleting the joint proxy object, or taking the joint proxy object caused deletion of the corresponding joint in the physics engine. (This is why each joint must have a unique name, so that the physics engine knows which joint is being referred to.) Deleting joints in an active jointed assembly will cause the connected bodies to disconnect. Deleting, deactivating, or taking a prim in an active jointed assembly will cause all joints connected to that prim to deactivate.

= Developer documentation =

== Patch structure ==

The patch for NINJA Physics is divided into 6 parts for better readability.

=== Part 1: data structures ===

Patch ninja-part1-joint_data_structures.patch declares the PhysicsJoint class and its subclass OdePhysicsJoint for storing joint information.

=== Part 2: abstract physics interface ===

Patch ninja-part2-physics_interfaces.patch alters PhysicsScene.cs with new methods for manipulating joints. The main idea is that a user of the physics engine can make joint requests or be notified of joint activity. Joint requests include requesting the physics engine to create or delete joints. Joint activity notification takes place through events that are fired whenever a joint is moved or a joint is deleted. These events allow the external scene to update scene information (position and orientation of joint proxy objects) to accurately reflect the state of the joints.

This part of the patch also modifies PhysicsActor.cs to contain the scene object part name and description. The physics engine links bodies together based by looking for physics actors whose names match the joint description.

=== Part 3: scene ===

Patch ninja-part3-scene.patch alters Scene.cs to allow NINJA Physics to be turned on/off. It also extends the behavior of DeleteSceneObject to delete the joint in the physics engine if the scene object corresponding to the joint (i.e. the joint proxy object) is deleted.

Also, this part of the patch alters SceneGraph.cs with callback handlers to respond to joint movement or joint deletion notifications from the physics engine. When a joint in the physics engine is moved/deactivated, its representation in the scene (the joint proxy object) is correspondingly moved/stopped from moving. Note that the joint has no direct representation (i.e. no body or geom) in the physics engine, so the physics engine has no knowledge of the scene graph's joint proxy object, necessitating this callback approach.

=== Part 4: SceneObjectPart ===

Patch ninja-part4-sceneobjectpart patches SceneObjectPart.cs to detect if the SceneObjectPart is a joint (based on its name of "balljoint-*" or "hingejoint-*"). If it is a joint, then requests to make this SceneObjectPart physical/non-physical are translated into calls to the physics scene to request creation/deletion of joints.

=== Part 5: ODE joints implementation ===

Patch ninja-part5-ode.patch is the ODE implementation of NINJA Physics.

ODEPrim.cs is patched to remove an optimization that prevents updates from being sent when the object position is almost stationary. This prevents rotational-only motion from being sent to the client, such as a fan blade rotating on a hinge.

OdePlugin.cs implements the creation and deletion of joints within ODE. Internal data structures keep track of associations between joints and bodies. Unprocessed joint requests (creation or deletion) are processed in the Simulate loop.

Joint deletion requests are handled immediately and the joint deleted callback is invoked to nofity the external scene of the joint change.

Joint creation requests are not handled immediately, because a joint can only be created if the bodies it is connecting already exist in the physics scene. Therefore, a joint creation request adds the new joint into a pending list. After processing of joint taints, a check is performed to see if any pending joints are still waiting for their respective bodies to appear in the physics engine. If such pending joints exist, and all of their bodies also exist, the joint is removed from the pending list and is actually created in ODE. Internal data structures also keep track of the association between bodies and the joints connected to that body.

Finally, whenever an physics actor (body) moves, it is checked if that body is connected by joints. If so, movement of the body implies movement of the joints connected to that body. Therefore, a joint moved callback is invoked to notify the external scene of the joint motion.

The DumpJointInfo function is useful for debugging.

=== Part 6: OpenSim.ini.example ===

Patch ninja-part6-ini.patch shows the OpenSim.ini option to control NINJA Physics.

== Joint states ==
Joints pass through the following states during their lifetime:

* Requested creation. In this state, the joint is not yet processed by main physics simulation loop.
* Pending. In this state, the joint is processed by main physics loop but does not yet exist in the physics engine. It is waiting for its constituent bodies to exist in the physics engine.
* Active. In this state, the joint exists in ODE and affects the ODE simulation. Furthermore, motion of the joint generates a joint moved event that can be subscribed to and acted upon.
* Requesting deletion. In this state, the joint has requested to be deleted from the main physics simulation loop, but that request has not been processed by the main simulate loop. Therefore the joint is still being simulated.
* About to delete. In this state, the joint is about to be deleted and a joint deactivated event is sent to notify subscribers of the joint's impending death.
* Deleted. The joint no longer exists in ODE, does not affect the physical simulation, and generates no further events.

= Limitations =

This section describes some current limitations and shortcomings of the current implementation and areas of continuing and future work.

== Naming limitations ==
* Each joint and each prim connected by a joint must have a unique name.
* Changes of joint names or prim names while the prim/joint is physical are not handled.
* When creating a joint, in the description field, use exactly one space between the names of the connected prims.
== Noisy logging ==
The current logging output contains too many debugging messages and should be reduced.

== Timing issues ==
* Extremely rapid toggling between physical and non-physical states, with the final state being "physical", can sometimes incorrectly lead to the joint's last state being "non-physical".
== Persistence of joints ==
* Region shutdown/startup persistence doesn't yet work. In other words, if you activate a jointed assembly then shutdown the region, upon region startup the recreated joints are not all perfectly reconstructed. It almost works, but some joint orientations are incorrect on region startup.
* load-oar persistence doesn't work due to threading/atomicity issues (see below).
== Atomicity issues ==
* Non-atomicity of viewer selection processing. If you select a group of non-physical prims and joints, and turn them all physical by clicking "physical" in the viewer, it is not guaranteed that the entire selected group will be turned physical in one tick of the simulation. It is therefore possible that part of the assembly will go "live" and start moving before all of the joints in the assembly have been constructed. This will lead to joint positions different than the original static specification of the joints.
* Non-atomicity of load-oar. Due to multi-threading, physics simulation continues while a load-oar is executing. This again means that parts of an assembly will go "live" and start moving before all of the joints in the assembly have been constructed.
== Accumulation of joint error ==
Repeatedly deactivating and reactivating a jointed assembly will lead to non-reversible accumulation of error in the joints. The joint proxy object saves the "position" of the joint but this information is not complete information about the joint. In particular, it does not contain any information about the joint error. For instance, imagine a ball and socket joint where, due to extreme forces acting on the parts, the ball and socket have been forced apart, leading to joint error. Currently, the joint proxy object only saves the joint position relative to one body, which is analagous to saving only the position of the ball but not the position of the socket. Upon deactivating and reactivating a joint with joint error, the current body positions are assumed to be 0% error, which means that the original joint error has been permanently "forgotten".
== Multi-user testing ==
This hasn't been tested in a multi-user environment. Single-user testing revealed occasional deadlocks which should hopefully now all be solved, but multi-user testing may expose more corner cases. My hope is that interested users of the OpenSim community can help test various multi-user scenarios. It will also be interesting to see how network latency and server load affect the user experience.

NINJA Physics

2008-12-19T11:10:53Z

Nlin: /* Quick start */

NINJA Physics

2008-12-19T11:05:47Z

Nlin: /* Part 6 - OpenSim.ini.example */

NINJA Physics

2008-12-19T11:05:14Z

Nlin: /* Naming limitations */

NINJA Physics

2008-12-19T10:48:07Z

Nlin: /* NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim */

NINJA Physics

2008-12-19T05:07:45Z

Nlin: New page: = NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim = Documentation in progress

= NINJA Physics: Networked INteractive Jointed Assemblies for OpenSim =

Documentation in progress

User:Nlin

2008-12-19T05:06:44Z

Nlin: New page: Some projects of mine: NINJA Physics

Some projects of mine:

[[NINJA Physics]]