Set Controller Value Functions

Animation Controllers - Quick Navigation

The following functions can be used to adjust the value of a controller using either absolute or relative values, and set an animation key or shift the whole animation curve, with the ability to commit or discard the animation curve changes after setting the value. Available in 3ds Max 2017 and higher.

Functions:

<value>SetControllerValue <controller>target <value>newValue <boolean>setKey <enum>{mode:#absolute|#relative}

Sets the controller specified by the first argument to the absolute value specified by the second argument when the fourth argument is #absolute, or increments the existing value by the second argument if the fourth argument is #relative.

When the third argument is set to True and the function is called while in Auto-Key mode, or inside an Animate context, a new animation key will be created at the current time in the controller.

When the third argument is set to False and the function is called while in Auto-Key mode, or inside an Animate context, and there is an existing key at the current slider time, the existing key will be set to the new value and the animation curve will be shifted temporarily in relation to it. Changing the current time or calling RestoreControllerValue() will discard the value changes.

Calling the CommitControllerValue() function will commit the changes, updating all existing keys to their new values, unless the changes have already been discarded.

<void>CommitControllerValue <controller>target

Makes the temporary changes to a controller's value applied using SetControllerValue() with third argument set to False permanent.

If this function is not called, the changes will be discarded as soon as the current time is changed.

If the RestoreControllerValue() function has been called after the SetControllerValue() and the CommitControllerValue() calls, the function will have no effect.

<void>RestoreControllerValue <controller>target

Discards the temporary changes to a controller's value applied using SetControllerValue() with third argument set to False permanent.

It can be used to programmatically achive a similar result to moving the time slider after a SetControllerValue() call, however the UI will not be updated to reset the value.

It has no effect if the changes have been already committed using CommitControllerValue(), or if the third argument of SetControllerValue() was set to True to set an animation key.

EXAMPLE:

b = box()
--> $Box:Box001 @ [0.000000,0.000000,0.000000]
c = b.height.controller = newDefaultFloatController()
--> Controller:Bezier_Float
setControllerValue c 100 true #absolute
--> 100
c.value
--> 100.0
setControllerValue c -10 true #relative
--> -10
c.value
--> 90.0

sliderTime = 0 --make sure the time slider is on frame 0
--> 0
select b --select the box
--> OK
max modify mode --show the box in the modify panel
--> OK

--Try to set an animation key with value 90+50=140 on frame 50 with the third argument set to false
with animate on at time 100 setControllerValue c 50 false #relative
--> 50
c.keys --there are no keys created, and the box is now 140 units tall
--> #keys()
c.value
--> 140

--Now let's set the third argument to true to create animation keys:
with animate on at time 100 setControllerValue c -40 true #relative
--> -40

--Checking the keys, the first key has the previous controller value 140 on frame 0
--The second key has the new value of 100 at frame 100:
for k in c.keys do format "% = %\n" k (k.value)
--> #Bezier Float key(1 @ 0f) = 140.0
--> #Bezier Float key(2 @ 100f) = 100.0

sliderTime = 100	
--Now let's try to temporarily modify the second key on frame 100 to an absolute value of 200:
with animate on at time 100 setControllerValue c 200 false #absolute
--> 200
--The command panel shows Height: 200.0 on frame 50, however 
--checking the keys, they still show the original values of 140.0 and 100.0:
for k in c.keys do format "% = %\n" k (k.value)
--> #Bezier Float key(1 @ 0f) = 140.0
--> #Bezier Float key(2 @ 100f) = 100.0
sliderTime -= 1
--> 49
sliderTime += 1
--> 50
--At this point, the Modify Panel will show 100.0 again, as the uncommited value was reset back.

--Let's do this again, but this time we will commit after the change:
with animate on at time 100 setControllerValue c 200 false #absolute
--> 200
CommitControllerValue c --commit the change
--> OK
--At this point, moving the time slider will not reset the new value anymore, it is committed to 200.0.
--But in addition, the first key on frame 0 was also shifted to 240.0!
for k in c.keys do format "% = %\n" k (k.value)
--> #Bezier Float key(1 @ 0f) = 240.0
--> #Bezier Float key(2 @ 100f) = 200.0

with animate on at time 50 setControllerValue c 42 true #absolute
--> 42
sliderTime = 50
--> 50
with animate on at time 50 setControllerValue c 24 false #absolute
--> 24
RestoreControllerValue c --we take back the change internally, but the Modify Panel still shows 42.0
--> OK
CommitControllerValue c --try to commit the change of 24.0 to the key and shift the whole animation curve
--> OK
sliderTime = 49
--> 49
sliderTime = 50
--> 50
--Since we restored the controller value before the commit, the value at frame 50 remains 42 and is not shifted to 24.
--The same is true for all other keys:
for k in c.keys do format "% = %\n" k (k.value)
--> #Bezier Float key(1 @ 0f) = 240.0
--> #Bezier Float key(2 @ 50f) = 42.0
--> #Bezier Float key(3 @ 100f) = 200.0