OpenSimulator - User contributions [en]

Physics Engine Interface

2011-09-14T07:33:57Z

Xadmin: /* PhysicsScene */

== Base Classes ==

''Note: I ([[User:Rknop]]) am trying to figure this out by looking at some of the code; my main interest is the NewtonPlugin. AS such, there are whole swaths of the physics engine, such as joints, that I have no clue about at the moment''

The base classes for a physics module can be found in OpenSim.Region.Physics.Manager. The physics module itself should be a subclass of Physics, e.g. OpenSim.Region.Physics.OdePlugin.

* '''<tt>PhysicsActor</tt>''' is the base class for both prims and avatars.
* '''<tt>PhysicsScene</tt>''' is the main base class that interfaces with the region's Scene.
* (others)

The Physics Scene doesn't access the Region Scene. The region scene will tell the physics engine about prims and avatars, and will send updates to the physics engine. It will then pull positions and velocities of objects and avatars out of the physics engine.

For the most part, the things that will be interfacing with the physics engine are the classes <tt>OpenSim.Region.Framework.Scenes.Scene</tt>, <tt>OpenSim.Region.Framework.Scenes.SceneObjectGroup</tt>, and <tt>OpenSim.Region.Framework.Scenes.SceneObjectPart</tt>

== The Plugin Class ==

If you're writing a Physics engine named Foo, you need to write a class OpenSim.Region.Physics.FooPlugin with the following methods:

* '''FooPlugin()''' — constructor
* '''bool Init()''' — (not sure exactly when this is called. return true)
* '''PhysicsScene GetScene(String sceneIdentifier)''' — return a FooScene, which is derived from PhysicsScene
* '''string GetName()''' — return the name that folks can use in OpenSim.ini to select this physics engine
* '''Dispose()''' — destructor

== PhysicsScene ==

Your class OpenSim.Region.Physics.FooScene must derive from OpenSim.Region.Physics.PhysicsScene. Members include:

;'''public override void Initialize(IMesher meshmerizer, IConfigSource config)'''
:Passes in the Meshing plugin to the Physics Plugin.

;'''public override PhysicsActor AddAvatar(string avName, PhysicsVector position, PhysicsVector size, bool isFlying)'''
:Scene calls this method when adding an avatar to the physics scene or changing appearance

;'''public override void SetWaterLevel(float baseheight)'''
:If water is simulated in your physics engine, this passes in the visual base height

;'''public override void RemovePrim(PhysicsActor prim)'''
:This gets called when a prim is made into something the physics engine no longer needs to know about. The physics engine should remove it from any internal lists of prims it is keeping track of.

;'''public override void RemoveAvatar(PhysicsActor character)'''
:Like RemovePrim, but for avatars.

;'''public override PhysicsActor AddPrimShape(string primName, PrimitiveBaseShape pbs, PhysicsVector position, PhysicsVector size, Quarternion rotation)'''
:Tells the physics engine to add a new prim it needs to keep track of. This prim is ''not'' a physical prim, but as long as it's not phantom, physical objects may collide with it, and thus the physics engine (may) need to know about it. (Unless the physics engine punts on collisions, as, for instance, NewtonPlugin does.) Comments in the code indicate that this method is slated to be removed....

;'''public override PhysicsActor AddPrimShape(string primName, PrimitiveBaseShape pbs, PhysicsVector position, PhysicsVector size, Quarternion rotation, bool isPhysical)'''
:Like the previous one, but you've got the flag that tells you if it's physical or not.

;'''public override void AddPhysicsActorTaint(PhysicsActor prim)'''
:When the scene makes a change to the Physics Scene, it informs the Physics Plugin that it tainted the object to give the physics scene a chance to update it's internal data during or before next step

;'''public override void GetResults()'''
:When the physics engine is multi-threaded (such as PhysX), GetResults would be called to Select the threads and wait until they're finished.

;'''public override bol IsThreaded'''
:A member that needs a get method. Returns if the Physics Plugin/Engine is Multi-Threaded

;'''public override void SetTerrain(float[] heightMap)'''
:Sets terrain using a flattened(strided) y-flipped float array of Constants.RegionSize by Constants.RegionSize. float val= heightmap[y * Constants.RegionSize + x]

;'''public override void DeleteTerrain()'''
:Remove terrain. (does this ever get called?)

;'''public override Dictionary<unit, float> GetTopColliders()'''
:Provides the Scene with information about the Physics Scene (requested through the Estate Module). uint is the unique ID of the object in the Simulator. float is a rating value.

;'''public override float Simulate(float timestep)'''
:This is the core function. This gets called by the main loop when it wants the Physics engine to do its magic and propagate forward the positions and velocities of all the stuff it knows about. The physics engine should update the Position and Velocity members of the PhysicsActor class it knows about (those things that have been added to it by the methods above). '''Important:''' when the physics engine thinks that things have changed enough for any given prims that the surrounding scene should updates it's own idea about the positions and velocities of those prims, it should call the RequestPhysicsterseUpdate() method of the changed PhysicsActors(). (The safest, but slowest, way to do this is for Simulate() to call this for every physical prim it knows about every time it is called.)
[http://www.gadgetsdotcom.com Gadgets]

== PhysicsActor ==

PhysicsActor represents both prims and characters. You may want to make separate classes for the two. You can get away with this because PhysicsActors are actually created by PhysicsScene. Your subclass of PhysicsScene has different methods called when an avatar or a prim is added to the scene, returning a PhysicsActor. You can return the appropriate subclass in each case.  Be aware, that these properties are not thread safe by default and multiple threads *will* reach in here. 

Members:

;'''int PhysicsActorType'''
:Needs get and set methods. Return ActorTypes.Prim or ActorTypes.Agent if it's a prim or an avatar.

;'''bool IsPhysical'''
:Needs get and set.  Returns true if the object has a RigidBody, False if it is static.  The Scene will set the object Static and Active here.

;'''PhysicsVector Position'''
:Needs get and set. If an object is physical, the physics engine keeps the "real" position for that object. However, it's the surrounding scene's impression of the position that gets rendered and sent to the client. It will pull the position out of the physics engine by looking at this member, and tell the physics engine about any external changes in its position through this member. Note that the scene doesn't automatically pull out the position, but only when it thinks it needs to. You can call the RequestPhysicsterseUpdate() method of PhysicsActor to ask the Scene to update its position for any given PhysicsActor. (See PhysicsScene.Simulate() above.)

;'''PhysicsVector Velocity'''
:Need get and set. Similar considerations to Position

;'''PhysicsVector RotationalVelocity'''
:Needs get and set Angular Velocity of the object being simulated 

;'''PhysicsVector Acceleration'''
:Needs get; there's no set method. The Linear Acceleration of the object 

;'''void SetAcceleration(PhysicsVector accel)'''
:Do what you'd think Acceleration.set would do

;'''PhysicsVector Size'''
:Needs get and set. Sets the scale of the object.

;'''float Mass'''
:Needs get; there is no set method at the moment.   The scene reaches requests the mass from the physics engine here 

;'''void SetMass(float mass)'''
:Instead of Mass.set

;'''void SetMomentum(PhysicsVector momentum)'''
:I am disturbed that this exists in addition to Velocity.set and SetMass....

;'''Quarternion Orientation'''
:Needs get and set.   Quaternion representing the orientation of the object in WorldSpace when non-physical.  It's in LocalSpace when it's a child object linked to a root object.

;'''bool ThrottleUpdates'''
:Needs get and set. I'm not sure what this means, exactly.  This informs the scene and physics engine to reduce the number of updates to save Resources. 

;'''bool IsColliding'''
:Needs get and set. True if object is colliding with another object 

;'''bool CollidingGround'''
:Needs get and set. True if object is colliding with the ground 

;'''bool CollidingObj'''
:Needs get and set True if object is colliding with another object (but not the ground) 

;'''bool Stopped'''
:Just needs get

;'''PhysicsVector CenterOfMass '''
:Just needs get. Returns the Center of Mass of the object.   In most cases that will be <0,0,0> 

;'''PhysicsVector GeometricCenter'''
:Just needs get. I doubt that anything is using this now..     

;'''PrimitiveBaseShape Shape'''
:Just needs set.  When a user changes the type of object to simulate, Shape gets set by the scene.   Going from a Cube, to a Sphere or Torus, for example. 

;'''PhysicsVector Force'''
:Needs get and set. I ''think'' this is a steady force (in N) always acting on the object.

;'''PhysicsVector Torque'''
:Needs get and set. Like Force, I think this is a steady torque operating on the object.

;'''void AddForce(PhysicsVector force, bool pushforce)'''
:This should apply a one-time impulse to the object of magnitude "force" Newton-seconds.  AddForce is used to move objects around in the PhysicsEngine (avatar too!).  PushForce means that one of the script engine pushes is being employed.

;'''void AddAngularForce(PhsyicsVector force, bool pushforce)'''
:A one-time angular impulse. See AddForce for more info on pushforce.

;'''int VehicleType'''
:(I don't know anything about the vehicle code requirements)

;'''void VehicleFloatParam(int param, float value)'''

;'''void VehicleVectorParam(int param, PhysicsVector value)'''

;'''void VehicleRotationParam(int param, Quarternion rotation)'''

;'''void SetVoulumeDetect(int param)'''
:This is some weird mode that can be set via a LSL function.  (Object receives collisions but doesn't cause a reaction)

;'''float Buoyancy'''
:Needs get and set

;'''bool FloatOnWater'''
:Just needs set

;'''float CollisionScore'''
:Needs get and set. I don't know what this is.

;'''bool Flying'''
:Needs get and set  (Avatar Flying = True, else, False)

;'''bool SetAlwaysRun'''
:Needs get and set. Avatar running -> True, Else false 

;'''unit LocalID'''
:Needs set. I don't know what this is. This is the simulator Unique ID for the object

;'''bool Grabbed'''
:Needs set. I'm not sure what this is,  when you control-click on an object

;'''void link(PhysicsActor obj)'''
:I haven't delved into how linking works in the physics engine. This says "link yourself to obj with obj as the root

;'''void delink()

;'''void LockAngularMomentum(PhysicsVector axis)'''

;'''bool Selected'''
:Just needs set. Gets set when this object is selected and deselected in the edit tools.

;'''void CrossingFailure()'''

;'''PhysicsVector PIDTarget'''
:Just needs set. A position to which an object is supposed to move. Correct! 

;'''bool PIDActive'''
:Just needs set.

;'''float PIDTau'''
:Just needs set. This is the timescale (in seconds) in which the object should move to PIDTarget when it is set to be PID Active.

;'''float PIDHoverHeight'''

;'''float PIDHoverActive'''

;'''PIDHoverType PIDHoverType'''

;'''float PIDHoverTau'''

;'''void SubscribeEvents(int ms)'''
:I do not know what sorts of events the PhysicsActor sends... hopefully I'll update this if/when I figure that out! It looks like you can ask for OnPositionUpdate, OnVelocityUpdate, OnOrientationUpdate, OnRequestTerseUpdate, OnCollisionUpdate, and OnOutOfBounds... but I have yet to fully understand the OpenSim event system, so I may be speaking out of the side of my mouth here.

:This actually gets called when the Script engine script handles collision, collision_start, and collision_end events.    The scene is requesting that the Physics Plugin send collision updates back to the scene every n Milliseconds.  If it's 0, then it's Physics Plugin default.  This also gets called for Avatar.  PhysicsActor has an method called SendCollisionUpdate that needs to be called to send collision data (pairs) back to the scene. 

;'''bool SubscribedEvents()'''

Hypergrid

2011-09-14T07:33:45Z

Xadmin: /* Development Meetings */

__NOTOC__
{{Quicklinks}}
 

==The OpenSim Hypergrid==

Also see [[Grider]]; [[Virtual World Model]]; [[HyperGrid Team]]

=== What is the hypergrid? ===


The hypergrid is an extension to opensim that allows you to link your opensim to other opensims on the internet, and that supports seamless agent transfers among those opensims. It can be used both in standalone mode and in grid mode. The hypergrid is effectively supporting the emergence of a Web of virtual worlds.

The basic idea for the hypergrid is that region/grid administrations can place hyperlinks on their map to hypergrided regions run by others. Once those hyperlinks are established, users interact with those regions in exactly the same way as they interact with local regions. Specifically, users can choose to teleport there. Once the user reaches the region behind the hyperlink, she is automatically interacting with a different virtual world without having to logout from the world where she came from, and while still having access to her inventory.

The hypergrid started as a GForge project, but it is now included in the standard distribution of OpenSim. To run your OpenSim instance in hypergrid mode, please see [[Installing_and_Running_Hypergrid|Installing and Running]].

=== Virtual World Hyperlinks ===
[[image:hghyperlink.jpg|250px|thumb|A Virtual World Hyperlink]]

We're all familiar with hypertext links on the Web. But what is a virtual world hyperlink?

In the hypergrid model, we consider the 2D map of the virtual world as the equivalent of a web page. As such, a VW hyperlink is simply a region on that map.

The default model of opensim-based virtual worlds already supports this concept of hyperlink, to some extent. When you teleport from one region to another via the map, chances are you are migrating your agent into a different opensim server. This migration is a glorified "agent transfer" that also exists, in rudimentary form, on the web when hypertext links are followed. The default model, however, imposes two very strong constraints on these hyperlinks:
# The entire map of regions is controlled by a central service known as the grid service, whose job is to provide a uniform view of the world to all of its regions.
# The only agents that can be transferred are those pertaining to users known to another central service, the user service; if the incoming user is not on that service's database, the agent transfer doesn't go through.

The hypergrid simply removes these two constraints.

First, it allows individual opensim instances to add "neighbors" to their local map, shifting the control of the map down from the grid server to individual opensim instances (although hyperlinks can also be served by grid servers if grid admins so wish). In doing so, the world becomes a lot more interesting and varied. The map that you see in one opensim instance may be completely different from the map that you see after you teleport via an hyperlink. As an opensim administrator, you are free to define what other opensims you want to see on your map.

Second, it allows the transfer of agents pertaining to foreigner users, i.e. users who are registered elsewhere. Instead of assuming one central user service, the hypergrid assumes an arbitrarily large number of such services distributed all over the world. As such, when agents are transferred among hypergrided opensims, a lot more information is passed about the corresponding user. That information includes the collection of servers that the transferring user needs.

=== Usage Scenarios ===

The following are some usage scenarios. There isn't a clear separation between these scenarios, there's a large overlap between them. This is also not an exhaustive list. The purpose of these descriptions is to give you some starting ideas for how to use the hypergrid in practice. Please feel free to add other interesting scenarios to this list.

{| class="wikitable"
|-
|
[[image:topoA.jpg|400px|left]]
|
'''Personal Worlds'''

This first scenario pertains to standalone opensims. Normally, standalones are completely disconnected from the internet. However, when run in hypergrid mode, standalones become network-able. As such, you can run your own world in your own computer, and link your world to whoever you want. For example, you can link to your friends' hypergrided opensims and to hypergrid gateways in open grids such as OSGrid.

The great thing about this scenario is that all of your assets are stored on your computer, and not on somebody else's server. You can back them up using ordinary backend tools. The not so great thing about this scenario is that all of your assets are stored on your computer! If your disk goes berserk, you loose them. (so make sure you make external backups regularly)

|-
|
[[image:topoB.jpg|400px|left]]
|
'''Communities'''

This second scenario is about communities, broadly construed. The idea here is that a group of people come together to support a small community grid, i.e. a common world where shared activities take place. But at the same time, the members of the community maintain their own standalone worlds. The standalones link to the community grid, and the community grid may link back to the individual members' worlds and other places of interest.

The members' identities are probably the identities they have on their standalones, and their assets are also probably stored there. The assets present in the community regions, however, are stored on the grid asset server.

|-
|
[[image:topoC.jpg|400px|left]]
|
'''Grid Public Regions'''

Walled-gardens are here to stay, and they serve many useful purposes. There is a hybrid mode for the hypergrid that some walled-garden grid operators may be interested in supporting. In this hybrid mode, most opensim instances on the grid run in normal, wall-garden mode, so no foreign visitors are allowed there - technically it is impossible to reach them. However, a few opensim instances on that grid can run in hypergrid mode, so that foreign visitors are allowed. This way, there is a gateway for grid-local users and arbitrary visitors to meet. This is also a good strategy for attracting new users to the grid, since random users are able to visit those gateway regions without having to sign up for an account upfront.

This hybrid mode is very similar to what happens on the web. For example, anyone can visit Facebook's public pages without having to sign up for a Facebook account. However, only Facebook users can go further inside.

|-
|
[[image:topoD.jpg|400px|left]]
|
'''Level Games'''

The normal version of OpenSim enforces a common map for all the regions on a grid. The hypergrid removes that constraint. As such, it becomes easy to design VW games where the world looks different depending of where the player is.

|-
|}

== Hypergrid Implementation ==

=== Hyperlinks and Agent Transfers ===

When you establish a link between your opensim and another, a message is sent out to that other opensim requesting information about it; the required information includes the network information of that opensim host, and the coordinates of its first region on its local grid in the form of a region handle. For example, suppose you are linking node X.com:9000, placing it in your local map at 900, 900. That opensim runs one or more regions that likely are not in 900, 900 on their own map; suppose the first region of that opensim is at 1100, 1100. From your point of view, it doesn't matter what those other coordinates are, and you don't need to know -- that's the key to being able to decentralize the "world" as given by a 2D map; you want to place it in your map at 900, 900. The "true" position of that simulator only matters for the LL viewer, when there are teleports between your world and that other opensim. This mapping between coordinate systems is the essence of hyperlinks for opensim; it's one simple but critical thing that the hypergrid implementation does. The mapping happens on the TeleportFinish event; instead of sending the local coordinates to the viewer, the hypergrid teleport wrapper sends the remote coordinates.

When an agent teleports through that hyperlink the following happens. First, before InformRegionOfChildAgent, the local opensim notifies the remote opensim of this foreign user via the "expect_hg_user" method. That message sends along the addresses of all the servers that this user uses, i.e. user, inventory and asset servers. The remote opensim places an entry for that user in its local user profile cache but not in its user database; the foreign user information is non-persistent. After that, the teleport process is exactly the same as the normal teleport process; the only difference is that the region handles are switched between the remote region's hyperlink position on the local grid and its actual position on its grid.

In summary, the two new concepts introduced by the hypergrid are the concept of an hyperlink and the concept of a "local user" vs. "[[Banning_Foreign_Users_in_Hypergrid|foreign user]]".

=== Inventory Access ===

Inventory access from abroad is done by wrapping the existing scene-inventory interactions with additional code that gets or posts inventory assets from/to the user's asset server. When inventory is accessed, the hypergrid wrapper checks if the user is foreign and, if she is, the wrapper simply brings the necessary assets from the user's asset server to the local asset cache and server; from then on, the wrapper passes the control to the existing inventory access functions. When something is added to inventory, the hypergrid wrapper is notified via an event, and posts the assets to the user's asset server. A cache of the exchanged item identifiers is maintained so that they aren't brought back over and over again.

The result is that hypergrided opensim instances end up interacting with several asset servers, instead of just one. That interaction is implemented in a straightforward manner by instantiating several GridAssetClient objects, instead of just one.

=== The Hypergrid Classes ===

Currently, the hypergrid is implemented outside of the OpenSim namespace, so that there is complete separation between what already exists and this new behavior. It has its own namespace, HyperGrid. In it, there are 4 sub-namespaces that follow directly the software architecture of OpenSim, namely:

* '''OpenSim.Framework''':
** ForeignUserProfileData extends UserProfileData by introducing information about the user's "home", namely the home address, port and remoting port. The user's home is not that user's user service; it's the opensim that the user has defined to be her home. This is necessary for supporting the home jump (Ctrl-Shift-H).
** HGNetworkServersInfo follows the spirit of NetworkServersInfo, although it neither extends it nor uses it. For now, it's a utility class whose two main functions are to convert domain names of servers to IP addresses, and to uniformly provide the answer to the question bool IsLocalUser(...).

* '''OpenSim.Region.Framework.Scenes.Hypergrid''':
** HGSceneCommunicationService extends SceneCommunicationService, overriding RequestTeleportToLocation. There are two very small but critical changes to the base method: (a) on the TeleportFinish event, we switch the region handles when the destination region is an hyperlink; (b) the connections at the end are always closed for hyperlink TPs.
** HGScene extends Scene, overriding TeleportClientHome(...). The only change to the base method is to stay away from the user server, for now, because the user service is still not completely wrapped up for foreign users. Once the user service is properly wrapped up, this class will become unnecessary.
** HGScene.Inventory is a partial class of HGScene, just like what happens in the OpenSim framework. This part of HGScene overrides some inventory-scene interaction methods, so that assets are fetched/posted from/to the user's asset server. Once that extra fetching/posting is done, these methods simply pass the ball to the base methods.
** HGAssetMapper: this is a new class specific to the hypergrid that manages the fetching and posting of assets between foreign regions where the user is and the user's asset server.

* '''OpenSim.Region.Communications.HyperGrid''' is a mashup of OpenSim.Region.Communications.*. This is the place where most of the hypergrid extension lies. One of the reasons for this is that the hypergrid communications part is doing one additional thing: it is making standalones network-able.
** HGCommunicationsStandalone extends CommuniationsLocal. Just as its base, it is a hub for the several network services available in standalone mode. The main difference is that those services are extensions of what's in OpenSim.
** HGCommunicationsGridMode extends CommunicationsManager directly. Again, it's a hub for the network services available in grid mode, those services being extensions of OpenSim.
** The cluster HGGridServices (superclass), HGGridServicesStandalone and HGGridServicesGridMode (subclasses) implements the OpenSim interfaces IGridServices and IInterRegionCommunications. The 2 subclasses are wrappers for LocalBackEndServices and OGS1GridServices, respectively. There is one common pattern throughout these classes: check if the region to talk to is an hyperlink; if it's not, simply delegate the work to LocalBackEndServices/OGS1GridServices; if it is, push the work to the base class HGGridServices. HGGridServices, in turn, does the management of hyperlink regions, and defines two additional pieces of inter-region protocol:
*** region_uuid: for linking regions
*** expect_hg_user: similar to the existing expect_user interface, but with a lot more information about the user being passed around, namely all the user's servers (inventory, asset, user, home, etc.)
** HGInventoryService extends LocalInventoryService and implements ISecureInventoryService. This class is the most obvious mashup of the pack, mixing local service access for standalone users and remote inventory access for when users are out and about. Right now, there is a fair amount of selective copy-and-paste, to stay away from the ugliness coming from OGS1InventoryService and OGS1SecureInventoryService. HGInventoryService is always a ISecureInventoryService. Its methods all follow the same pattern: check if the user is a local standalone user; if it is, pass the work to the base method (in LocalInventoryService); if it's not perform secure remote access.
** HGUserServices wraps OSG1UserServices, but it's not functional yet.

* '''OpenSim.Region.CoreModules.HyperGrid''' is a collection of 3 region modules:
** HGWorldMapModule extends WorldMapModule. It reuses almost everything from the base class. The only small change is in RequestMapBlocks, where it tries to send Offline mapblocks to the client.
** HGStandaloneInventoryService and HGStandaloneAssetService do what their names say. They are region modules that allow access to inventory and assets for standalones, when the standalone user is out and about. In spirit, there is a lot in common between these modules and the REST inventory/asset plugin. Unfortunately, that plugin could not be used because it defines a completely different interface than that used by existing inventory and asset servers, and the access for the hypergrid must use a consistent interface.

== Installing and Running ==

Please see [[Installing and Running Hypergrid]]

== Hypergrid and Security ==

Please see [[Hypergrid Security]]

== Banning Foreign Users ==

Please see [[Banning Foreign Users in Hypergrid]]

== Public Hypergrid Nodes ==

Please see [[Public Hypergrid Nodes]].

== Hypergrid Lists ==
Please see [[Hypergrid Lists]].

== Development Meetings ==
[http://www.gadgetsdotcom.com Gadgets]
[[Hypergrid Meetings]]

[[Category:Hypergrid]]