# IRiPhysicsCommand Interface Reference

Inherits IDispatch.

List of all members.

## Public Member Functions
HRESULT | RegisterObj ([in]BSTR bstrObjName,[in] BSTR bstrEngineName)
HRESULT | UnRegisterObj ([in] BSTR bstrObjName,[in] BSTR bstrEngineName)
HRESULT | StartSimulation ([in] BSTR bstrEngineName)
HRESULT | StopSimulation ([in] BSTR bstrEngineName)
HRESULT | SimpleCollision ([in] BSTR objname1,[in] BSTR objname2,[in] RtBool precision,[out, retval] RtBool *collision)
HRESULT | InitCollision ([in] BSTR SpaceName)
HRESULT | AddPhysAttr ([in] BSTR ObjName)
HRESULT | RemovePhysAttr ([in] BSTR ObjName)
HRESULT | CreateEngine ([in] BSTR bstrSpaceRootName,[out, retval] BSTR *bstrEngineName)
HRESULT | AddPhysAttrAt3D ([in] BSTR bsTarget,[in] BSTR bsNode,[in] VARIANT vPosX,[in] VARIANT vPosY,[in] VARIANT vPosZ,[out, retval] VARIANT *pVal)
HRESULT | AddEnvAttrAt3D ([in] BSTR bsTarget,[in] BSTR bsNode,[in] VARIANT vPosX,[in] VARIANT vPosY,[in] VARIANT vPosZ,[out, retval] VARIANT *pVal)
HRESULT | CreateToolbar ()
HRESULT | AddEnvAttr ([in] BSTR ObjName)
HRESULT | RemoveEnvAttr ([in] BSTR ObjName)
HRESULT | AddWind ([in] BSTR SpaceName,[in] RtBool local)
HRESULT | Collision ([in] VARIANT vCollType,[in, defaultvalue("")] BSTR ObjName)
HRESULT | ActivatePhysWidget ([in] BSTR bstrWidgetName)
HRESULT | Register ()
HRESULT | OpenPanel ()
HRESULT | OpenNodePanel ([in] BSTR bstrPanelName,[in] LONG dwAspect)
HRESULT | SceneCollision ([in] BSTR bstrName,[in] RtUshort option,[out, retval] VARIANT *ppCollInfo)
HRESULT | PeerCollision ([in] BSTR bstrName1,[in] BSTR bstrName2,[in] RtUshort option,[out, retval] VARIANT *ppCollInfo)
HRESULT | CollisionResponse ([in] BSTR bstrName,[in] VARIANT pCollInfo,[in] VARIANT pSpeed,[in] VARIANT pRotation)
HRESULT | MoveObject ([in] BSTR bstrName,[in] VARIANT pSpeed,[in] VARIANT pRotation,[in] float time)
HRESULT | AddImpulse ([in] BSTR bstrTargetObj,[in] VARIANT force,[in] VARIANT torque)
HRESULT | ObjectParam ([in] BSTR bstrTargetObj,[in] int flag,[in] VARIANT vCog,[in] VARIANT vInertia,[out, retval] float *volume)
HRESULT | UpdatePosition ([in] BSTR bstrName,[in] float time)
HRESULT | CreateFunctionSet ([out, retval] VARIANT *ppFnSet)
HRESULT | AddClothAttr ([in] BSTR ObjName)
HRESULT | RemoveClothAttr ([in] BSTR ObjName)
HRESULT | ResetClothFixation ([in] BSTR ObjName)
HRESULT | ResetAttribute ([in] BSTR bstrObjName,[in] BSTR bstrAttrName)

## Detailed Description

The IRiPhysicsCommand interface provides basic methods, that enable the management of physical simulation in Workspace. It includes methods for starting and stopping the simulation and methods for setting the physical parameters of objects in the scene. Using interface's methods, it is not only possible to start or stop simulation in various spaces, it also allows for directly affecting a running simulation, by adding or removing objects.
Root-level name in the scripting engine's name space: Physics

## Member Function Documentation

HRESULT IRiPhysicsCommand::RegisterObj | ( | [in] BSTR | bstrObjName,
|  | [in] BSTR | bstrEngineName |
| ) |  |  |

Adds object with physical attributes to simulation controlled by the physics engine. Both object and engine must be in the same space. If the simulation is running, the object is immediately included in the simulation.

Parameters:

  | bstrObjName | [in] Full name identification of object.
  | bstrEngineName | [in] Full name identification of physics engine.

Use the following syntax if you want to add an object to the simulation.

     Physics.RegisterObj('/Project/Space 3D/Sphere', '/Project/Space 3D/PhysEngine');

HRESULT IRiPhysicsCommand::UnRegisterObj | ( | [in] BSTR | bstrObjName,
|  | [in] BSTR | bstrEngineName |
| ) |  |  |

Removes an object with physical attributes from the simulation controlled by the physics engine.
Both object and engine must be in the same space. If the simulation is running, the object is immediately excluded from the simulation.

Parameters:

  | bstrObjName | [in] Full name identification of object.
  | bstrEngineName | [in] Full name identification of physics engine.

Use the following syntax if you want to remove an object from the simulation.

     Physics.UnRegisterObj('/Project/Space 3D/Sphere', '/Project/Space 3D/PhysEngine');

HRESULT IRiPhysicsCommand::StartSimulation | ( | [in] BSTR | bstrEngineName | ) |

Starts simulation controlled by physics engine with name bstrEngineName.
Simulation is started in the space in which the specified physics engine is present.

Parameters:

  | bstrEngineName | [in] Full name identification of physics engine.

     Physics.StartSimulation('/Project/Space 3D/PhysEngine');

HRESULT IRiPhysicsCommand::StopSimulation | ( | [in] BSTR | bstrEngineName | ) |

Stops simulation controlled by physics engine with specified name in bstrEngineName.

Parameters:

  | bstrEngineName | [in] Full name identification of physics engine.

     Physics.StopSimulation('/Project/Space 3D/PhysEngine');

HRESULT IRiPhysicsCommand::SimpleCollision | ( | [in] BSTR | objname1,
|  | [in] BSTR | objname2,
|  | [in] RtBool | precision,
|  | [out, retval] RtBool * | collision |
| ) |  |  |

Checks collision between two objects with two levels of precision:

- With object bounding boxes. Set precision to false for this option to take effect.
- With object mesh intersections. Set precision to true for this option to take effect.

Parameters:

  | objname1 | [in] Full name identification of first object.
  | objname2 | [in] Full name identification of second object.
  | precision | [in] Collision precision, if precision is FALSE, the bounding box of each object is used, if precision is TRUE, the object mesh to mesh intersections are checked.

Returns:
  collision [out, retval] Returns TRUE if collision occurred, FALSE if there is no collision.

        var owner = System.ThisOwner();
        var obj1 = owner + '/Sphere';
        var obj2 = owner + '/Sphere, 1';
        var target = owner + '/PhysEngine';
        if(Physics.SimpleCollision(obj1, obj2, false))
        {
         Physics.StopSimulation(target);
        }

HRESULT IRiPhysicsCommand::InitCollision | ( | [in] BSTR | SpaceName | ) |

Initialize collision detection mechanism for given space.

Parameters:

  | SpaceName | [in] Full name identification of space.

        var owner = System.ThisOwner();
        Physics.InitCollision(owner);

HRESULT IRiPhysicsCommand::AddPhysAttr | ( | [in] BSTR | ObjName | ) |

Set the default physical attributes for specified object.

Parameters:

  | ObjName | [in] Full name identification of object.

        var owner = System.ThisOwner();
        var obj1 = owner +'/Sphere';
        Physics.AddPhysAttr(obj1);

HRESULT IRiPhysicsCommand::RemovePhysAttr | ( | [in] BSTR | ObjName | ) |

Removes physical attributes from object.

Parameters:

  | ObjName | [in] Full name identification of object.

        var owner = System.ThisOwner();
        var obj1 = owner +'/Sphere';
        Physics.RemovePhysAttr(obj1);

HRESULT IRiPhysicsCommand::CreateEngine | ( | [in] BSTR | bstrSpaceRootName,
|  | [out, retval] BSTR * | bstrEngineName |
| ) |  |  |

Creates a physics engine node in the specified space.

Parameters:

  | bstrSpaceRootName | [in] Full name identification of space.

Returns:
  bstrEngineName [out, retval] Returns full name identification of created physics engine node.

        var owner = System.ThisOwner();
        var daName = Physics.CreateEngine(owner);
        System.Alert(daName);

HRESULT IRiPhysicsCommand::AddPhysAttrAt3D | ( | [in] BSTR | bsTarget,
|  | [in] BSTR | bsNode,
|  | [in] VARIANT | vPosX,
|  | [in] VARIANT | vPosY,
|  | [in] VARIANT | vPosZ,
|  | [out, retval] VARIANT * | pVal |
| ) |  |  |

Applies physical attributes onto object that is located in specific point in given view

Parameters:

  | bsTarget | [in] - Full name identification of view.
  | bsNode | [in] - Full name identification of template physics attributes node
  | vPosX | [in] - x position.
  | vPosY | [in] - y position.
  | vPosZ | [in] - z position.

Returns:
  pval [out,retval] Returns full name identification of created physics node.

HRESULT IRiPhysicsCommand::AddEnvAttrAt3D | ( | [in] BSTR | bsTarget,
|  | [in] BSTR | bsNode,
|  | [in] VARIANT | vPosX,
|  | [in] VARIANT | vPosY,
|  | [in] VARIANT | vPosZ,
|  | [out, retval] VARIANT * | pVal |
| ) |  |  |

Applies local environment attributes onto object that is located in specific point in given view

Parameters:

  | bsTarget | [in] - Full name identification of view.
  | bsNode | [in] - Full name identification of template local environment attributes node
  | vPosX | [in] - x position .
  | vPosY | [in] - y position.
  | vPosZ | [in] - z position.

Returns:
  pval [out,retval] Returns full name identification of created local environemnt node.

HRESULT IRiPhysicsCommand::CreateToolbar | ( |  | ) |

CreateToolbar.

HRESULT IRiPhysicsCommand::AddEnvAttr | ( | [in] BSTR | ObjName | ) |

Sets default local environmental attributes for object.

Parameters:

  | ObjName | [in] Full name identification of object.

        var owner = System.ThisOwner();
        var obj1 = owner +'/Sphere';
        Physics.AddEnvAttr(obj1);

HRESULT IRiPhysicsCommand::RemoveEnvAttr | ( | [in] BSTR | ObjName | ) |

Removes local environmental attributes from object.

Parameters:

  | ObjName | [in] Full name identification of object.

        var owner = System.ThisOwner();
        var obj1 = owner +'/Sphere';
        Physics.RemoveEnvAttr(obj1);

HRESULT IRiPhysicsCommand::AddWind | ( | [in] BSTR | SpaceName,
|  | [in] RtBool | local |
| ) |  |  |

Adds a wind node to the specified space.

Parameters:

  | SpaceName | [in] Full name identification of space.
  | local | [in] If TRUE, wind is local, if FALSE wind is global.

        var owner = System.ThisOwner();
        Physics.AddWind(owner, true);

HRESULT IRiPhysicsCommand::Collision | ( | [in] VARIANT | vCollType,
|  | [in, defaultvalue("")] BSTR | ObjName |
| ) |  |  |

Enable/disable collision precision in simulations for specified object.

Parameters:

  | vCollType | [in] TRUE = enable , FALSE = disable.
  | ObjName | [in] Object name, if objname == "" selected object is considered.

        var owner = System.ThisOwner();
        var obj1 = owner + '/Sphere';
        Physics.Collision(true, obj1);

HRESULT IRiPhysicsCommand::ActivatePhysWidget | ( | [in] BSTR | bstrWidgetName | ) |

Activates physics widget for current selected object.

Parameters:

  | bstrWidgetName | [in] widget name: PhysMoveWidget, Fix1Widget, Fix2Widget, LocEnvWidget, CogWidget, ClothFixWidget, SpeedWidget, RotationWidget, AccWidget, RotAccWidget

HRESULT IRiPhysicsCommand::Register | ( |  | ) |

Register special objects from physics package to cooperate with other packages.

HRESULT IRiPhysicsCommand::OpenPanel | ( |  | ) |

Open phys engine panel. It shows up in stack area at right.

     Physics.OpenPanel();

HRESULT IRiPhysicsCommand::OpenNodePanel | ( | [in] BSTR | bstrPanelName,
|  | [in] LONG | dwAspect |
| ) |  |  |

Open phys node or phys env node panel in stack area at right.

Parameters:

  | bstrPanelName | [in] - panel name: possible values 'phys', 'env', 'cloth'.
  | dwAspect | [in] - number of aspect to show.

     Physics.OpenNodePanel('phys', 0);

HRESULT IRiPhysicsCommand::SceneCollision | ( | [in] BSTR | bstrName,
|  | [in] RtUshort | option,
|  | [out, retval] VARIANT * | ppCollInfo |
| ) |  |  |

Check collision of specified object with scene.

Parameters:

  | bstrName | [in] Full name identification of object.
  | option | [in] Collision parameters, IRiPhysicsCommand::RtCollPrecision. 0 = Full precision. 1 = Only one contact point and normal for two colliding object. 2 = Bounding box collision/precision. 3 = Get only lists of intersected triangles. 4 = Cloth-like precision if first object is cloth.

Returns:
  ppCollInfo [out, retval] Collision data.

        var collisionInfo = params.ConValue('collisionInfo');  // Script attribute created as "Physics Package/Collision Data"
        var owner = System.ThisOwner();
        var target = owner + '/Sphere';
        collisionInfo = Physics.SceneCollision(target, 0);

HRESULT IRiPhysicsCommand::PeerCollision | ( | [in] BSTR | bstrName1,
|  | [in] BSTR | bstrName2,
|  | [in] RtUshort | option,
|  | [out, retval] VARIANT * | ppCollInfo |
| ) |  |  |

Check collision between two objects.

Parameters:

  | bstrName1 | [in] Full name identification of the first specified object.
  | bstrName2 | [in] Full name identification of the second specified object.
  | option | [in] Collision parameters, IRiPhysicsCommand::RtCollPrecision.

Returns:
  ppCollInfo [out, retval] Collision data.

        var collisionInfo = params.ConValue('collisionInfo');  // Script attribute created as "Physics Package/Collision Data"
        var owner = System.ThisOwner();
        var target = owner + '/Sphere';
        var target1 = owner + '/Sphere, 1';
        collisionInfo = Physics.PeerCollision(target, target1, 0);

HRESULT IRiPhysicsCommand::CollisionResponse | ( | [in] BSTR | bstrName,
|  | [in] VARIANT | pCollInfo,
|  | [in] VARIANT | pSpeed,
|  | [in] VARIANT | pRotation |
| ) |  |  |

Calculate and set collision response to given phys object.

Parameters:

  | bstrName | [in] Full name identification of the specified object with phys attr.
  | pCollInfo | [in] Collision data obtained with PeerCollision or SceneCollision.
  | pSpeed | [in] Speed of object at the time of collision, returned value is speed after collision.
  | pRotation | [in] Rotation of object at the time of collision, returned value is rotation after collision.

        var owner = System.ThisOwner();
        var target = owner + '/Sphere';
        var speed = System.CreateDO('Math Package/Point Data');
        var rotation = System.CreateDO('Math Package/Point Data');

        //set speed
        speed.x = 5.0;
        speed.y = -5.0;
        speed.z = 0.0;

        //set rotation
        rotation.x = 10.0;
        rotation.y = 5.0;
        rotation.z = 0.0;

        var collInfo = Physics.SceneCollision(target, 0);
        if (collInfo.Collision)
            {Physics.CollisionResponse(target, collInfo, speed, rotation)}

HRESULT IRiPhysicsCommand::MoveObject | ( | [in] BSTR | bstrName,
|  | [in] VARIANT | pSpeed,
|  | [in] VARIANT | pRotation,
|  | [in] float | time |
| ) |  |  |

Update position of object with speed and rotation values.

Parameters:

  | bstrName | [in] Full name identification of the specified object with phys attr.
  | pSpeed | [in] Speed of object.
  | pRotation | [in] Rotation of object.
  | time | [in] Integration time step.

        //move object
        var timestep = 0.040;
        Physics.MoveObject(target, speed, rotation, timestep);

HRESULT IRiPhysicsCommand::AddImpulse | ( | [in] BSTR | bstrTargetObj,
|  | [in] VARIANT | force,
|  | [in] VARIANT | torque |
| ) |  |  |

Add impulse to phys object.

Parameters:

  | bstrTargetObj | [in] Full name identification of the specified object with phys attr.
  | force | [in] Impulse force (acceleration).
  | torque | [in] Torque force (angular acceleration).

        var force = System.CreateDO('Math Package/Point Data');
     var torque = System.CreateDO('Math Package/Point Data');
     force.x = 10000; force.y = 10000;
     torque.z = 250;
     var owner = System.ThisOwner();
     var target = owner + '/ring1';
     Physics.AddImpulse(target, force, torque);

HRESULT IRiPhysicsCommand::ObjectParam | ( | [in] BSTR | bstrTargetObj,
|  | [in] int | flag,
|  | [in] VARIANT | vCog,
|  | [in] VARIANT | vInertia,
|  | [out, retval] float * | volume |
| ) |  |  |

Return the invariant parameters of specified object like cog, inertia, volume ...

Parameters:

  | bstrTargetObj | [in] Full name identification of the specified object with phys attr.
  | flag | [in] If flag == 0 cog and inertia are in local coordinate system, else in world coordinate system.
  | vCog | [in] Center of gravity.
  | vInertia | [in] Inertia matrix.

Returns:
  volume [out,retval] Object volume.

HRESULT IRiPhysicsCommand::UpdatePosition | ( | [in] BSTR | bstrName,
|  | [in] float | time |
| ) |  |  |

Update position of specified object with phys attr, with collision evaluation.

Parameters:

  | bstrName | [in] Full name identification of the object with phys attr.
  | time | [in] Integration time step.

        var owner = System.ThisOwner();
        var target = owner + '/Sphere';
        var timestep = 0.040;
        Physics.UpdatePosition(target, timestep);

HRESULT IRiPhysicsCommand::CreateFunctionSet | ( | [out, retval] VARIANT * | ppFnSet | ) |

Create physics helper function set.

Returns:
  ppFnSet [out, retval] Returned initialized scriptable interface for physics function set.

     var fnSet = Physics.CreateFunctionSet();
     if (fnSet)
     {
      var owner = System.ThisOwner();
      var target = owner + '/Sphere';
      var volume = fnSet.Volume(target);

     }

HRESULT IRiPhysicsCommand::AddClothAttr | ( | [in] BSTR | ObjName | ) |

Add and set the default cloth attributes for specified object.

Parameters:

  | ObjName | [in] Full name identification of object.

        var owner = System.ThisOwner();
        var target = owner + '/Sphere';
        Physics.AddClothAttr(target);

HRESULT IRiPhysicsCommand::RemoveClothAttr | ( | [in] BSTR | ObjName | ) |

Remove cloth attributes from specified object.

Parameters:

  | ObjName | [in] Full name identification of object.

        var owner = System.ThisOwner();
        var target = owner + '/Sphere';
        Physics.RemoveClothAttr(target);

HRESULT IRiPhysicsCommand::ResetClothFixation | ( | [in] BSTR | ObjName | ) |

Reset cloth object fixation.

Parameters:

  | ObjName | [in] Full name identification of object.

        var owner = System.ThisOwner();
        var target = owner + '/Sphere';
        Physics.ResetClothFixation(target);

HRESULT IRiPhysicsCommand::ResetAttribute | ( | [in] BSTR | bstrObjName,
|  | [in] BSTR | bstrAttrName |
| ) |  |  |

Resets specific attribute for object.

Parameters:

  | bstrObjName | [in] - Full name identification of object.
  | bstrAttrName | [in] - attribute name: possible values 'Speed', 'Rotation', 'AccSpeed', 'AccRotation'.

     Physics.ResetAttribute('', 'Speed');