Modifying the Items in a Referenced Object

When you modify items within a referenced object, MotionBuilder writes the changes in Python script and stores them within the FBX file. This enables the changes to persist when you save and reopen the FBX scene that contains the referenced object.

For example, if you rotate the NS:Cube and scale the NS:Cube 1 in the following scene, the changes and the file reference object are stored inside the FBX scene file when the file is saved.

The next time when this scene is opened, the file reference object is created while loading and the changes are also applied to it. You can view the reference edit by calling the GetRefEdit function on the file reference object.

lFileReference = FBFindObjectByFullName( "FileReference::NS" )
print( lFileReference.GetRefEdit() )

This function returns the reference edit in Python script for the current reference path if no parameter is provided. The output is as follows:

from pyfbsdk import *

###########################################################################
#pArgList[0] indicates if instancing is happening or not.
#pArgList[1:] indicates the namespace list that the reference edit will affect.
###########################################################################
def FBApplyReferenceEdits( pArgList ):
    for pNamespace in pArgList[1:]:
        lComp = FBFindObjectByFullName( "Model::" + pNamespace + ":Cube 1" )
        if lComp != None:
            lProperty = lComp.PropertyList.Find("Lcl Scaling")
            if lProperty != None:
                lProperty.SetString( "{5.29,5.29,5.29}" )

        lComp = FBFindObjectByFullName( "Model::" + pNamespace + ":Cube" )
        if lComp != None:
            lProperty = lComp.PropertyList.Find("Lcl Rotation")
            if lProperty != None:
                lProperty.SetString( "{-8.00208984532112,-45.9720647907999,12.5577795991379}" )

        FBSystem().Scene.Evaluate()
###########################################################################
#pArgList[0] indicates if instancing is happening or not.
#pArgList[1:] indicates the namespace list that the reference edit will affect.
###########################################################################
def FBRevertReferenceEdits( pArgList ):
    for pNamespace in pArgList[1:]:
        lComp = FBFindObjectByFullName( "Model::" + pNamespace + ":Cube 1" )
        if lComp != None:
            lProperty = lComp.PropertyList.Find("Lcl Scaling")
            if lProperty != None:
                lProperty.SetString( "{1,1,1}" )

        lComp = FBFindObjectByFullName( "Model::" + pNamespace + ":Cube" )
        if lComp != None:
            lProperty = lComp.PropertyList.Find("Lcl Rotation")
            if lProperty != None:
                lProperty.SetString( "{0,0,0}" )

        FBSystem().Scene.Evaluate()

Additionally, MotionBuilder also provides a query based system using dirty flags for retrieving a list of changes. You can get a list of objects and their property changes. The two functions: GetSelfModified and GetContentModified are used for checking the dirty flags of a reference object or a reference item.

A self dirty flag is put on the item and a content dirty flag is put on the reference object whenever the referenced item changes. The following figure illustrates this concept.

The red circle represents the reference object and the blue circle represents the referenced items. The result after the dirty flags are set is shown on the right.

If a property of a referenced item changes, a self dirty flag is put on the property and a content dirty flag is put on the reference object. The following figure illustrates this concept. The blue boxes represent the properties of a referenced item. The result after the dirty flags are set is shown on the right.

Following are some changes that set dirty flags in the example scene.

Connection changes between reference items and non-referenced scene objects

If you parent a non-referenced NewCube onto a referenced NS:Cube, the flag kFBSelfConnectionSrcObjectModified is set to True on NS:Cube. The kFBContentConnectionModifiedMask flag is set to True on the reference object NS. The following code checks for these flags.

lNSCube = FBFindObjectByFullName( "Model::NS:Cube" )
lNewCube = FBFindObjectByFullName( "Model::NewCube" )
lNSCube.Parent = lNewCube
lFileReference = FBFindObjectByFullName( "FileReference::NS" )
print( lFileReference.GetContentModified(FBPlugModificationFlag.kFBContentConnectionModified) )
print( lNSCube.GetSelfModified( FBPlugModificationFlag.kFBSelfConnectionModifiedMask ) )

You can also determine whether this change occurred on source or destination.

print( lNSCube.GetSelfModified(FBPlugModificationFlag.kFBSelfConnectionSrcObjectModified) )
print( lNSCube.GetSelfModified(FBPlugModificationFlag.kFBSelfConnectionDstObjectModified) )

Connection changes between reference items and properties of non-referenced scene objects

If you create an animation track (non-referenced scene object) in the Story tool and include NS:Cube to its tracked contents, the Details and TravellingNode properties of the animation track is connected with NS:Cube. The following code checks for the relevant dirty flags: kFBSelfConnectionSrcPropertyModified and kFBSelfConnectionDstPropertyModified.
```
lNSCube = FBFindObjectByFullName( "Model::NS:Cube" )
lNSCube.GetSelfModified( FBPlugModificationFlag.kFBSelfConnectionSrcPropertyModified )
lNSCube.GetSelfModified( FBPlugModificationFlag.kFBSelfConnectionDstPropertyModified )
```
Property value changes

If you move a referenced NS:Cube in 3D space, for example, from 3D position (10, 10, 10) to (100,-9, 99), the kFBSelfDataModified flag is set to True for the Translation property on the cube and the kFBContentDataModified flag is set to True for the cube.

After you check these flags and know that the cube's property is modified, you can get the original value of the property.
```
lNSCube = FBFindObjectByFullName( "Model::NS:Cube" )
print( lNSCube.PropertyList.Find("Lcl Translation").OriValueAsString() )
```
Property state changes

If you set the Translation property of the referenced NS:Cube to be animatable, the kFBSelfStateModified flag is set to True for the property and the kFBContentStateModified flag is set to True for the cube.
Custom property creation

If you create a custom property on a referenced NS:Cube, the kFBSelfCustomPropertyModified flag is set to True on the cube and the kFBContentCustomPropertyModified flag is set to True on all the parent file reference objects.

Modifying the Items in a Referenced Object

Was this information helpful?