Relative Name

ActionSource or ActionSources store paths to parameters as relative names. A relative name consists of the SIObject.FullName or SIObject::GetFullName of the Parameter or Parameter without the Model or Model name. For example, the full name of the posx parameter on a cube under a model called Cricket is Cricket.cube.kine.global.posx. The relative name makes an action source easy to share between different models because a parameter's relative name is the same everywhere: cube.kine.global.posx.

Tip

If you are running scripts that create action sources and then instantiate them in the Mixer or Mixer, you may have had a connection mapping dialog pop up asking how to connect the action on the parameters. This often happens when you create a source using the parameter's full name instead of a relative name when the parameter is nested in a model (and it won't happen if the parameter is under the scene root because in that case the parameter does not use the scene root in its full name).

JScript Example: Getting the RelativeName

Here is a JScript function that takes the specified Parameter object and returns its relative name. GetRelativePathForTarget uses regular expressions to find and remove the name of the model from the FullName of the specified parameter.

function GetRelativeNameForTarget( in_param )
{
	var mdlname = in_param.Model.FullName;
	if ( mdlname == "Scene_Root" ) {
		return in_param.FullName;
	} else {
		var tmp = in_param.FullName;
		var re = new RegExp( mdlname + ".", "i" );
		return tmp.replace( re, "" );
	}
}

Python Example: Getting the RelativeName

Here's the same function in Python. This of GetRelativePathForTarget also uses regular expressions to remove the name of the model from the FullName of the specified parameter.

def GetRelativeNameForTarget( in_param ) :
	import string as s
	mdlname = in_param.Model.FullName
	if mdlname == "Scene_Root" :
		return in_param.FullName
	else :
		return s.replace( in_param.FullName,  mdlname + ".", "" )

C++ Example: Getting the RelativeName

Here's a similar function for the C++ API. However, since C++ has doesn't have the power of regular expressions for string manipulation, a workaround is provided using the C++ API CString::IsEqualNoCase function instead.

CString GetRelativeNameForTarget( Parameter& in_param )
{
	Model mdl = in_param.GetModel();
	CString mdlname = mdl.GetFullName();
	if ( mdlname.IsEqualNoCase(L"Scene_Root") ) {
		// We don't care about an object under the scene root 
		// (it automatically uses relative names anyways)
		return in_param.GetFullName();
	} else {
		CString tmp = in_param.GetFullName();
		CString lookfor = mdlname + L".";
		CString foundsofar = L"";
		CString relpath = L"";
		
		// This loop looks to find the modelname in the full path. 
		// When it finds it, it collects the rest of the string 
		// as the relative name 
		for ( ULONG i=0; i<tmp.Length(); ++i ) {
			if ( foundsofar.IsEqualNoCase(lookfor) ) {
				relpath += tmp[i];
			} else {
				foundsofar += tmp[i];
			}
		}
		
		// Return the relative name extracted from the full path
		return relpath;
	}
}