ReplicantBody - a character animation toolkit

Click on the image for a short movie!

ReplicantBody is a character animation toolkit written in C++, built upon Cal3D, ConfigScript and OpenSceneGraph.

Copyright (C) 2003 VRlab, Umeå University

Authors
Peter Sunna - sunna@hpc2n.umu.se
Anders Backman - andersb@cs.umu.se
Daniel Sjölie - deepone@hpc2n.umu.se

Project Home Page: http://www.vrlab.umu.se/research/replicantbody

License

ReplicantBody is distributed under GNU LGPL, see http://www.opensource.org/licenses/lgpl-license.php.

Contents

./

setup_env.bat - setup script for Visual Studio
build.bat - build script (using Visual Studio devenv/msdev)
make_rbody_all.bat - makes libraries cal3d, ConfigScript, ReplicantBody and executable rbodyTest

make - make script for Unix
make_rbody_all - makes libraries cal3d, ConfigScript, ReplicantBody and executable rbodyTest

./cal3d

Cal3d v0.9 (CVS version as of 2003-11-24)
http://cal3d.sourceforge.net

./ConfigScript

ConfigScript v1.2
Copyright (C) 2003 Anders Backman, VRlab, Umeå University

./ReplicantBody

ReplicantBody v0.1

./ReplicantBody/include/rbody - ReplicantBody includes
./ReplicantBody/include/rbodyTest - rbodyTest includes
./ReplicantBody/src/rbody - ReplicantBody source files
./ReplicantBody/src/rbodyTest - rbodyTest source files
./ReplicantBody/Visual Studio/ - MS Visual Studio project files
./ReplicantBody/lib/ - local repository for library files
./ReplicantBody/bin/ - local repository for binary file rbodyTest
./ReplicantBody/data/characters/ - character files
./ReplicantBody/data/scene/
	environment.flt - Model used by rbodyTest
	material and attribute files for environment.flt
./ReplicantBody/data/bizguy1/
	bizguy1.c* - Cal3D data files
	bizguy1.rbody - Replicant Body configuration file
./ReplicantBodydata/bizguyanimations - Cal3D animation files

Dependencies

Installation

Untar the tarball rbody.tar.gz
Example: Type "tar xvcf rbody.tar.gz" from command line, or double click file if Winzip or similar program is installed.

Windows - Visual Studio

Open command line window by clicking "Start" - "Run" and then typing "cmd" or "command".
Go to directory "rbody" created earlier.

Run setup_env.bat
 - First argument is directory with ReplicantBody, cal3d and ConfigScript
 - Second argument is directory with OSG, Producer, OpenThreads and pthreads
Example: setup_env.bat c:\projects\rbody c:\tools
Run make_rbody_all.bat

Both debug and release configuration will be compiled and linked. Observe that you will get errors when compiling the Cal3D projects if you don't have all Cal3D utilities downloaded. The important thing is, however, that the base Cal3D library (included in ReplicantBody package) is compiled and linked without errors.

To work with ReplicantBody from within Visual Studio, type "devenv /useenv ReplicantBody\Visual Studio\ReplicantBody.sln" from rbody directory. If you have Visual Studio 6, replace "devenv" with "msdev". The "/useenv" parameter tells Visual Studio that you should use the environment variables set up by setup_env.bat.

Linux/Unix

Set environment variable INSTALL_PREFIX to your install directory. 
Example: setenv INSTALL_PREFIX /home/s/sunna/installed
Run make_rbody_all

Demo program rBodyTest

Windows

To run demo program rbodyTest.exe:

Easy way:
Run runme.bat

Hard way:
Make sure environment variable REPLICANTBODY_FILE_PATH is pointing to ReplicantBody/data
Example: set REPLICANTBODY_FILE_PATH=c:\projects\rbody\ReplicantBody\data
Make sure environment variable OSG_FILE_PATH is pointing to ReplicantBody\data
Example: set OSG_FILE_PATH=%OSG_FILE_PATH%;c:\projects\rbody\ReplicantBody\data

Run "ReplicantBody/bin/rbodyTest.exe scene/environment.flt characters\character2.char"

Linux/Unix

To run demo program rbodyTest:

Make sure environment variable REPLICANTBODY_FILE_PATH is pointing to ReplicantBody/data.
Example: setenv REPLICANTBODY_FILE_PATH /home/s/sunna/projects/rbody/ReplicantBody/data
Make sure environment variable OSG_FILE_PATH is pointing to ReplicantBody/data.
Example: setenv OSG_FILE_PATH $OSG_FILE_PATH:/home/s/sunna/projects/rbody/ReplicantBody/data
Run "bin/rbodyTest scene/environment.flt characters/character2.char"

Key bindings

The following keys can be used to control the characters in the demo:

'Up arrow' - walk forward
'Control + Up arrow' - run forward
'Down arrow' - stand still
'Left arrow' - turn left
'Right arrow' - turn right
'F1' - stand
'F2' - long idle
'F3' - middle idle
'Delete' - look left
'End' - look right
'Page Up' - toggle active character
'Page Down' - toggle active character

The distribution package with all source code, containing ReplicantBody, ConfigScript and Cal3D, can be downloaded from the Sourceforge project site.

If you don't mind the source code and just want to see the demo program rbodyTest in action, you should instead download the Windows' binaries from.

Will be on the sourceforge website soon.

Just run "runme.bat" to start the demo.

High and low priority actions

In order to make is easier to control the motion of the character, the motions have been divided into two broad categories: high priority actions and low priority actions (also refered to as activities). These are in turn divided into looping and non-looping.

Low priority actions are animations which often affects most parts of the body. Examples are "walk", "stand" and "sit down". They can only be played one at a time since the other way around doesn't make sense. High priority actions often only affects small portions of the body. Examples are "wave", "hit" and "kick". High priority actions can be executed in parallell, look in one direction while waving is one example of that. Furthermore it is possible to play one low priority action while executing a high priority action, like walking and waving.

The low priority action container

The low priority action container handles all actions in a queue. Whenever an action is first in the queue, all animations that it consist of (see animations types) are extracted and blended into the Cal3D model with a given weight. Each animation connected to an action is played once if either the action is non-looping or if there is another animation waiting in the queue. In all other cases the animations will loop until another action is placed in the queue. When this happens, the active animations will finish their current loops, blend out from the Cal3D model, and give place for the animations connected to that new action.

The high priority action container

The high priority action container is a bit different from the low priority action container since it doesn't act like a queue. Whenever an action is placed in the container, all animations it consist of are extracted and time stamped. On update all inactive animations which start time has passed are executed. Active looping actions are re-executed when their duration time has passed. All inactive animations that have been executed are removed from the container.

Different animation types

Different animation types have been created to simplify the animation of the character. The animations types makes it easier to combine cal3d animations and blend them in an apropriate way to get a desired result. The animations types are defined in a configuration script (.rbody) for each core body and is connected to an action name for easy access.

Base Animation

The base animations are key-framed motion data, used by Cal3D to actually animate the character. The other animation types use the base animations mixed in sequences and blends to create new motions.

• Cal3D filename
• Animation name
• Action name
• Speed
• Is looped

The animation name is only used when refering to the animation from other animation types. The action name is used when refering to this animation from "outside". Note that several animations can be connected to the same action name, thus there can exist several animations for the action "ACT_WALK" for example. If the animation has got a translation, that is, the character is supposed to move when the animation is played, the speed variable tells how fast in units per second. Note that this speed isn't used when actually moving the character when i field of view (FOV). Remember that all translations should be removed from animations before exported from 3DSMax.

Scripted animation

Scripted animations make it possible to queue low priority actions that will be played. For example, play first "walk", then "lie down" followed by "crawl". Scripting also works for high priority actions, but then the animations aren't queued, but instead executed at a given time. An example of this is execute "hit" after 10 seconds, and 20 seconds after that, execute "kick".

• Animation name
• Action name
• Name of animation 1
• Start time of animation 1
• ...
• Name of animation n
• Start time of animation n

The animation name is the name of the animation, which can refer to a base animation, a scripted animation or a blended animation. The start time is only used when the animation is treated as high priority. Animations placed in the queue

Blended animation

A blended animation is a mix of two or more similar animations. Each animation influences the model with a different weight, making it possible to create new motions.

• Animation name
• Action name
• Name of animation 1
• Weight of animation 1
• ...
• Name of animation n
• Weight of animation n

The animation name is the name of the animation and, as with scripted animations, this name can refer to a base animation, a scripted animation or a blended animation. The weight tells how much the animation should influence the resulting motion. It should be in the interval (0,1) and the sum of all weights should add up to 1.

Speed blend animation

A speed blend animation makes it possible to vary the speed of a low priority action. It contains two base animations with defined speeds, meaning that their motion is supposed to move the character forward with that speed.

• Animation name
• Action name
• Name of animation 1
• Speed of animation 1
• Name of animation 2
• Speed of animation 2
• Default speed

The default speed parameter tells what speed to use if no other speed is given. To determine how the animations should be weighted to move at a given speed linear interpolation is used.

Angle (degree) blend animation

An angle blend animation works the same way as a speed blend, but instead of making it possible to vary the speed of a low priority action, the direction of a high priority action can be specified. For example this can be used to have the character look in a specified direction.

• Animation name
• Action name
• Name of animation 1
• Angle animation 1 is representing
• Name of animation 2
• Angle animation 2 is representing

To determine the weights of the animations when a direction angle is given, the same method as for speed blend i used.

Animation helpers

Contact bones

Contact bones is the bones in the skeleton from which the translation of the animation is calculated. Usually this is the bones in the feet. Defined in core body configuration file for (.rbody).

Direction bones

Direction bones are bones from which you can get the direction. For example helpful when you want to know in what direction your character is looking. Defined in core body configuration file for (.rbody).

Conflicting high priority actions

It is possible to define high priority actions that cannot be executed at the same time to avoid conflicts. Defined in core body configuration file for (.rbody).

In-between animations

In-between animations are used when there is need for a transition animation between two other animations, for example is "stand up" an in-between animation for "sit" and "walk". Defined in core body configuration file for (.rbody).

Examples

A core character is used to share common data between several characters that use the same configuration. There is one configuration file (.rbody) for each core character. See "data/bizguy1/bizguy1.rbody" in the distribution directory structure for an example on how to specify a core character with a .rbody configuration file. It is in the configuration file the different animation types and the animation helpers are defined. See .rbody configuration file specification below. A manager keeps track of which .rbodys you have loaded, so the only thing you need to know when creating a new character is the name of the .rbody file yo use.

In this new version characters have been introduced. A character is a body with a unique name that is tied to a core body. Characters are specified in a .char file (see specification below). The OSG plugin char (included in this package) makes it possible to treat the characters as any other OSG plugin. A character manager keeps track of all loaded characters, making sure they have a unique id and are accessible.

There is an example in include/rbodyTest and src/rbodyTest in the distribution directory structure on how to setup and control a character that is described in a .char file using the character manager. An example on how to use only a .rbody configuration file for the same task is also given. See include/rbody/osg/OsgBody.h to get an understanding of the "body" interface. OsgBodyNode is derived from a osg::MatrixTransform and have a OsgBody.

For ReplicantBody to work the environment variables REPLICANTBODY_FILE_PATH and OSG_FILE_PATH need to be set correctly. REPLICANTBODY_FILE_PATH and OSG_FILE_PATH should both point to the "ReplicantBody/data" directory. REPLICANTBODY_FILE_PATH is used when ReplicantBody manager creates a character. Examples are:

g_ReplicantBodyMgr->createCharacter("rbody_file", "name")
g_ReplicantBodyMgr->loadCharacterFile("char_file")

osg::Node *arg_node = osgDB::readNodeFile("char_file")

Another important thing is that Cal3D must be compiled with CAL_16BIT_INDICES defined. This could either be done using command line arguments to the compiler or by uncomment the appropriate line in cal3d/src/cal3d/global.h. In this distribution the setup scripts are already configured to do this.

Configuration file .char specification

----- Configuration File Begins -----

	Character {
  		ID "name" // Unique id
  		CoreName "path to .rbody-file" // See spec below
  		Position [ x y z ] // Position in world coordinates
  		Orientation [x y z] // Orientation in Euler angles
	}
	
	...

	Character {
		...
	}

----- Configuration File Ends -----

Configuration file .rbody specification

----- Configuration File Begins -----

	# This is a comment
	// This is also a comment

	# Activity = low priority animation

	# All Cal3D data files should be stored in the
	# same directory
	path “path to Cal3D data files”
	skeleton “name of Cal3D skeleton data file”
	default_act "action to use at startup"
	scale scale_float # Scaling to use
	foot_offset offset_float # Distance between foot bone and ground

	# Bones used when calculating character speed
	ContactBones {
		bone_name "name of bone in skeleton"
		...
		bone_name "name of bone in skeleton"

	}

	# Bones from which you can get the direction
	DirectionBones {

		head_bone "name of bone in skeleton"
		...
		head_bone "name of bone in skeleton"

	}	

	# A core character can consist of several animations
	# Each animation is connected to an action name
	# It is the action name that is used when refering to
	# an animation/animation type
	Animation {
		name “name of animation”
		filename “name of cal3d file with animation”
		act_name “name of action connected to”
		act_weight weight_of_act_float # Default is 1
		speed translation_speed_float # Default is 0
		is_looped is_looped_int # 0 if non-looping
		is_default is_default_int # 0 if not default
	}

	# AnimationDegree makes it easy to combine two actions
	# that are executed in different directions
	# For example, a simple "look at" can be done by specifying
	# an animation of head bone turned right as animation 1 with
	# "degree" set to 90 (the cal3d animation must contain at least 2 frames)
	# Animation 2 should then contain an animation with head bone 
	# turned left and "degree" should be set to -90
	AnimationDegree {
		name “name of animation”
		act_name “name of action connected to”
		act_weight weight_of_act_float # Default is 1
		Animation {
			name “name of animation 1”
			degree angle_representat_of_anim_1_float
		}
		Animation {
			name “name of animation 2”
			degree angle_representat_of_anim_2_float
		}
	}
	
	# AnimationSpeed works in the same way as AnimationDegree
	# but here the speed can be varied
	AnimationSpeed {
		name “name of animation”
		act_name “name of action connected to”
		act_weight weight_of_act_float # Default is 1
		default_speed default_speed_float
		Animation {
			name “name of animation 1”
			degree speed_representat_of_anim_1_float
	}
		Animation {
			name “name of animation 2”
			degree speed_representat_of_anim_2_float
		}
	}

	# AnimationBlend can contain two or more animations
	# The sum of all animations’ weights should add up to
	# 1
	AnimationBlend {
		name “name of animation”
		act_name “name of activity/action connected to”
		act_weight weight_of_act_float # Default is 1
		Animation {
			name “name of animation 1”
			weight blend_weight_of_anim_1_float
		}
		Animation {
			name “name of animation n”
			weight blend_weight_of_anim_n_float
		}
	}

	# An AnimationScript can have one or more animations
	# The start_time is only used when the animations are
	# treated as prioritized, else the animations are
	# queued
	AnimationScript {
		name “name of animation”
		act_name “name of activity/action connected to”
		act_weight weight_of_act_float # Default is 1
		Animation {
			name “name of animation 1”
			start_time start_time_of_anim_1_float
		}
		Animation {
			name “name of animation n”
			start_time start_time_of_anim_n_float
		}
	}

	# A core character consist of several meshes
	Mesh {
		name “name of mesh”
		filename “name of Cal3D data file with mesh”
		is_default is_default_int # 0 if not default
	}

	# The materials get their material ids in the order
	# they are loaded. Thus, the first loaded material
	# gets id 0, the second gets id 1, and so on
	Material {
		filename “name of Cal3D file with material”
	}

	# A material set is used to connect thread ids
	# (which get their id parsing by their name for
	# a figure in 3DS) to material ids
	MaterialSet {
		name “name of material set”
		is_default is_default_int # 0 if not default
		Connection {
			thread_id thread_id_int
			material_id material_id_int
		}
	}
	
	# Actions that cannot be executed at the same time
	# are listed here
		ConflictingActions {
		action_1 “name of action 1”
		action_2 “name of action 2”
	}

	# The InBetweenActivity is used to transition
	# smoothly between different activities, that is,
	# use another activity in-between if their end
	# and start poses differs dramatically
	
	InBetweenActivity {
		start_activity “name of start activity”
		end_activity_ “name of end activity”
		inbetween_activity “name of inbetween activity”
	}

----- Configuration File Ends -----

Screenshots

	Video from the hit RainingMen?

Some information of the system (osgVortex) from which the screenshots has been made:

• The character (Replicant in red shirt) is controlled by a simple state machine telling him to walk between three boxes.
• The state machine is scripted in the Lua scripting language, from which the whole simulation (physics, osg, 3D sound) can be controlled.
• All the boxes is physically simulated using rigid body dynamics.
• The character is also interacting with the physical objects wich can be seen in image6.
• The red transparent boxes are triggers for playing a randomly choosed event sound.
• The boxes generates contact sound when colliding with the floor and each other.