Physics Engine Interface

Revision as of 11:47, 18 September 2009

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.

• PhysicsActor is the base class for both prims and avatars.
• PhysicsScene 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.

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)

public override PhysicsActor AddAvatar(string avName, PhysicsVector position, PhysicsVector size, bool isFlying)

public override void SetWaterLevel(float baseheight)

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 void 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.)

public override void 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)

(I don't know what taints are, so I can't document them yet....)

public override void GetResults()

public override bol IsThreaded

A member that needs a get method.

public override void SetTerrain(float[] heightMap)

public override void DeleteTerrain()

public overrid Dictionary<unit, float> GetTopColliders()

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.)