A SmartBody simulation can be controlled through the use of a Python API. The Python API can be used to start and stop the simulation, create or remove a character, configure characters, place objects in the scene and so forth. A full reference of the Python API can be found in Appendix 2: Python API for SmartBody.
How to Send Python Commands to SmartBody
There are several ways to send Python commands, depending on how you are interfacing with SmartBody.
Sending Python Commands via VHMessage
If your SmartBody instance is connected to an ActiveMQ server via the VHMessage system, you can send a message formatted as follows:
sb <python command goes here>
Where the sbm commands tell SmartBody to interpret the message, and the command python tells SmartBody to interpret everything after the space as a Python command.
Similarly, you can send:
sb scene.run(scriptName)
where the 'scriptName' file is an existing .py file that is located in SmartBody's asset path.
Sending Python Commands via the SmartBody application sbgui
If you are using the default SmartBody application (sbgui), you can send a Python command by doing the folllowing:
Choose Window->Command Window then enter the Python command under the tab named 'Python'. To execute the block of Python code, press the 'Run' button.
Sending Python Commands via C++
If you are using a separate renderer (such as Ogre, Unity, etc), Python commands can be sent to SmartBody through the C++ interface.If you are using the smartbody-dll interface, you can send Python commands via the VHMessage interface by using the following functoin:
bool ProcessVHMsgs( const char * op, const char * args );
where 'op' is "sb" and the second parameter is the Python command. For example:
ret = ProcessVHMsgs( "sb", "n = scene.getNumCharacters()");
Python API Overview
The Python API uses a module called SmartBody, which includes the following classes:
| Class Name | Description |
|---|---|
| SBObject | Base SmartBody object. Most classes derive from this object. |
| SBAttribute | Dynamic attributes that can be queried, modified, created and deleted on any SmartBody object. |
| SBScene | Describes the entire simulation scene, and start point for accessing simulation, BML, resources and other objects needed. |
| SBPawn | An object that could be a character or other non-living object in the scene. |
| SBCharacter | A character, subclass of SBPawn. |
| SBSkeleton | The joint hierarchy of a character |
| SBJoint | Joint, part of the SBSkeleton |
| SBService | Services that exist in the scene. Services are non-tangible scene objects that manage various aspects of SmartBody. Examples of services include: physics, steering, bonebus, vhmessages, etc. |
| SBMotion | An animation for a character or pawn. |
| SBController | Controller used to manage different behaviors of a character. Examples of controllers are: gaze controller, reaching/grabbing controller, eyelid controller, facial animation controller, etc. |
| SBAnimationBlend | Parameterized animation states. Could be a simple animation, or a complex combination of individual motions. |
| SBAnimationTransition | Transitions between animation states. |
| SBFaceDefinition | Describe a set of animations or blendshapes used to control facial animation and lip syncing. |
| SBEventManager | Maintains and controls events that occur within SmartBody |
| SBSimulationManager | Maintains and controls the simulation flow, including starting, stopping, pausing and changing the simulation frame rate. |
| SBBmlProcessor | BML (Behavior Markup Language) processor, for sending BML commands. |
| SBSteerManager | Controls character steering around obstacles. |
| SBPhysicsManager | Controls and maintains character and pawn physics states. |
| SBReachManager | Maintains and controls reaching/grabbing and touching behaviors. |
| SBStateManager | Manages animation states and transitions. |
| SBGestureManager | Manages gestures for each character. |
| SBProfiler | Inline performance profiler. |
By default, the SmartBody module is imported into the scene, as well as the following objects:
| Object | Description |
|---|---|
| scene | instance of SBScene. The scene contains most of the functions needed to access, create and remove all SmartBody-related object. Can also be retrieved via: getScene() |
| bml | The BML processor, which can be used to send BML commands to various character. Can also be retrieved via: scene.getBMLProcessor() |
| sim | The simulation manager, which can be used to start, stop and pause the simulation. Can also be retrieved via: scene.getSimulationManager() |
| asset | The asset manager which holds all the motions, skeletons, models and other assets. |
