`transitions` — A quick and easy way to automate transforming your nodes¶

When writing a game you’ll often want to apply a set of known transformations to a nodes.Node. For example, you want your Node to move 100 pixels to the right, then wait 3 seconds and return 100 pixels to the left. Or you’ll want the node to pulsate (smoothly change its scale between some min and max values), or rotate back and forth. YOu may want to have any combination of those effects applied (either one after another or parallel). There’s an unlimited number of such visual transformations and their combinations, that you may want to have in your game.

You can of course implement all this, by having a set of boolean flags, time trackers, etc. and use all those helper variables to manually change the desired properties of your nodes from within the update() method. But there is an easier way: the mechanism is called Transitions. A single Transition object is a recipe of how a given property of a Node (position, scale, rotation, color, sprite, etc.) should change over time. Transition can be played once, given number of times or in a loop. You can also chains transitions to run one after another or in parallel.

Transitions are the primary way of creating animations. Since animation is nothing else than just changing Node’s sprite over time, the transition mechanism comes useful for that purpose.

Common transition parameters¶

Note: All transitions are immutable.

To create a Transition you’ll typically need to pass the following parameters:

advance_value - advance value for given transition type (e.g. target position for NodePositionTransition).
duration - transition duration time, in seconds
advance_method - an enum value of AttributeTransitionMethod type which determines how the advance_value will be applied to modify the appropriate node property.
- AttributeTransitionMethod.set - node’s property will be changed towards the advance_value over time
- AttributeTransitionMethod.add - node’s property will be changed towards the current value + advance_value over time
- AttributeTransitionMethod.multiply - node’s property will be changed towards the current value * advance_value over time
loops - Optional. How many times the transition should “play”. Set to 0 to play infinite number of times. Default is 1.
back_and_forth - Optional. If set to True, the transition will be played back and forth (that counts as one “loop”). Default is False.
easing - Optional. An enum value of easings.Easing - specifies the rate of change of a value over time. Default is Easing.none which really means a linear easing.

Note

The duration parameter always refers to one loop, one direction. So for example, transition with the following set of parameters: duration=1., loops=3, back_and_forth=True will take 6 seconds. 1 second played back and forth is 2 seconds, and it will be played 3 times, hence a total time of 6 seconds.

Note

If back_and_forth is set to True, the transition will play back and forth which counts as one loop.

All transitions use linear easing. More built-in easing types are to be added soon.

Examples¶

Change position of a node, from (100,100) to (30, 70) over 2 seconds.

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
node.transition = NodePositionTransition(Vector(30, 70), 2.)

Change position of a node, from (100,100) by (30, 70), i.e. to (130, 170) over 2 seconds.

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
node.transition = NodePositionTransition(Vector(30, 70), 2., advance_method=AttributeTransitionMethod.add)

Change position of a node, from (100, 100) by (x30, x70), i.e. to (3000, 7000) over 2 seconds.

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
node.transition = NodePositionTransition(Vector(30, 70), 2., advance_method=AttributeTransitionMethod.multiply)

Change position of a node, from (100,100) to (30, 70) then back to the initial position (100,100) over 2 seconds.

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
node.transition = NodePositionTransition(Vector(30, 70), 2., back_and_forth=True)

Change position of a node, from (100,100) to (30, 70) then get back to the initial position over 2 seconds. Repeat it 3 times.

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
node.transition = NodePositionTransition(Vector(30, 70), 2., loops=3, back_and_forth=True)

Change the scale of a node (twice on the X axis and three times on the Y axis) over 1 second.

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
node.transition = NodeScaleTransition(Vector(2, 3), 1.)

Change the scale of a node (twice on the X axis and three times on the Y axis) over 1 second. Repeat indefinitely (creating pulsation effect).

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
node.transition = NodeScaleTransition(Vector(2, 3), 1., loops=0)

Rotate the node 90 degrees clockwise over 3 seconds

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
node.transition = NodeRotationTransition(math.pi/2, 3.)

Change position of a node by (150, 100) over 2 seconds, then enlarge it twice over 1 second, then do nothing for 2 seconds, finally rotate it 180 degrees over 3 seconds. Play the whole sequence two times, back and forth.

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
transitions = [
    NodePositionTransition(Vector(150, 100), 2., advance_method=AttributeTransitionMethod.add),
    NodeScaleTransition(Vector(2, 2), 1.),
    NodeTransitionDelay(2.),
    NodeRotationTransition(math.pi, 3.)
]
node.transition = NodeTransitionsSequence(transitions, loops=2, back_and_forth=True)

Do everything the same like in previous example but have the node simultaneously change its color to red, back and forth in 1500 milisecond intervals.

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
transitions = [
    NodePositionTransition(Vector(150, 100), 2., advance_method=AttributeTransitionMethod.add),
    NodeScaleTransition(Vector(2, 2), 1.),
    NodeTransitionDelay(2.),
    NodeRotationTransition(math.pi, 3.)
]
color_transition = NodeColorTransition(Color(1,0,0,1), 1.5, loops=0, back_and_forth=True)

node.transition = NodeTransitionsParalel([
    color_transition,
    NodeTransitionsSequence(transitions, loops=2, back_and_forth=True)
])

Change position of a node, from (100,100) to (30, 70) over 2 seconds and call function my_func when the transition ends.

def my_func(transitioning_node):
    print('Function called!')

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
node.transition = NodeTransitionSequence([
    NodePositionTransition(Vector(30, 70), 2.),
    NodeTransitionCallback(my_func)])

Change sprite of a node, creating an animation effect:

spritesheet = Sprite(os.path.join('assets', 'gfx', 'spritesheet.png')
frames = split_spritesheet(spritesheet, Vector(100,100)) # cut the spritesheet into <Sprite> instances
animation = NodeSpriteTransition(frames, duration=2., loops=0, back_and_forth=False)
node = Node(position=Vector(100, 100), transition=animation)

Change z_index of a node over time:

node = Node(position=Vector(100, 100), sprite=Sprite('image.png'))
node.transition = NodeZIndexSteppingTransition([1,2,3,4,5,6,10,100], 1000)

`NodePositionTransition` reference¶

class transitions.NodePositionTransition(advance_value, duration, advance_method=AttributeTransitionMethod.set, loops=1, back_and_forth=False, easing=Easing.none)¶

Use this transition to change Node’s position gradually over time, towards given advance_value or by given advance_value.

The advance_value param must be a geometry.Vector and is the target position value (or position change value)