## SetMappingRule

### Introduced

v1.0

### Description

Modifies a rule in a connection or value mapping template, or in a clip's local value map.
Note that you cannot change the left-hand side (the Items part) of a rule in a clip's value map.

### Scripting Syntax

    SetMappingRule( MappingTemplate, From, [To], [Index], [Active], [PoseOffset] );

### Parameters

Parameter | Type | Description
--- | --- | ---
MappingTemplate | String | Mapping template or a clip value map. The value map of a clip is named ".actionclip".
From | String | The Map From part of a connection mapping rule, the Parameter part of a value mapping rule, or the Item part of a clip value mapping rule.
To | String | The Map To part of a connection mapping rule, the Expression part of a value mapping rule, or the Expr part of a clip value mapping rule.
Index | Integer | Specifies the rule to modify. Rules are numbered starting at 1, but an index of 0 or 1 refers to the first rule. Default Value: 0 (the first rule)
Active | Integer | Sets the activeness of the rule. Default Value: -1
Possible Values: | Description:
-1 | Don't change the current activeness setting.
0 | Deactivate the rule
1 | Activate the rule.
PoseOffset | Integer | Sets the pose offset activeness for the object. Default Value: -1
Possible Values: | Description:
-1 | Don't change the current pose offset setting.
0 | Deactivate the pose offset.
1 | Activate the pose offset.

### Examples

#### VBScript Example

    ' This example illustrates several mapping template commands.

    ' It creates an Action on a sphere, then uses a value mapping

    ' template to create an offset effect when this Action is instanced.

    ' Then it creates a connection mapping template so the sphere

    ' animation can be applied to a number of different objects (using a

    ' wildcard to do this).  Finally, the second clip (driving the cones)

    ' is accessed as a value map itself, and clip effects on it are

    ' created using SetMappingRule.

    NewScene , False

    ' Create some objects for our example.

    set oSphere = CreatePrim( "Sphere", "MeshSurface" )

    set oCone = CreatePrim( "Cone", "MeshSurface" )

    Duplicate oCone, 4

    posParams = "/kine.local.posx,kine.local.posy,kine.local.posz"

    ' Make an Action with the sphere moving diagonally.

    SetPositionKey oSphere, 1, -5, -3, 0

    SetPositionKey oSphere, 50, 5, 3, 0

    set oSource = StoreAction( , oSphere & posParams, 2, "Diagonal", True, 1, 50 )

    ' Create a value map and add some rules to it to map the

    ' sphere animation to be negated in X position and offset

    ' in Y.  We use a big index to indicate the rule should

    ' be added at the end.

    CreateEmptyValueMap "Scene_Root", oValMap

    AddMappingRule oValMap, oSphere & ".kine.local.posx", "(this)*-1", 10000

    AddMappingRule oValMap, oSphere & ".kine.local.posy", "(this)-5", 10000

    ' Instantiate a clip which uses this value map to modify

    ' the sphere animation.

    set oClip = AddClip( "Scene_Root", oSource, , , 1, "Sphere", , oValMap )

    ' Create a connection map, and add a single rule to it

    ' that will map the sphere animation to all cones, using

    ' a wildcard.

    CreateEmptyConnectionMap "Scene_Root", oCnxMap

    AddMappingRule oCnxMap, oSphere, "cone*"

    ' Instantiate a clip which uses this connection map to

    ' connect the sphere source to all the cones.

    set oClip = AddClip( "Scene_Root", oSource, , , 1, "Cones", oCnxMap )

    ' Bonus part...  For fun we'll modify the value mapping of each

    ' item in the cone clip, treating it like it's a fixed-size value

    ' map (can't add new items to it).

    clip = oClip & ".actionclip"

    offsetAmt = 0

    n = GetNumMappingRules( clip )

    for i = 1 to n

    	GetMappingRule clip, i, param, expr, active

    	if right( param, 4 ) = "posy" then

    		SetMappingRule clip, param, "(this)+time*" & offsetAmt, i, active

    		offsetAmt = offsetAmt + 1

    	end if

    next

    '==================================================

    ' Helper method to key an object somewhere at a given frame.

    '==================================================

    sub SetPositionKey( in_oObj, in_frame, in_posX, in_posY, in_posZ )

    	Translate in_oObj, in_posX, in_posY, in_posZ, siAbsolute, siParent, siObj, siXYZ

    	SaveKey in_oObj & posParams, in_frame

    end sub

### See Also

AddMappingRule CreateConnectionMap CreateValueMap DeleteMappingRule GetMappingRule GetNumMappingRules