Animations are a way to animate cards while interacting with the player. An animation is organized as a chain of animation blocks (AnimationBlock class:
res://addons/cardengine/animation/animation_block.gd source). Each block has 3 sequences (AnimationSequence class:
res://addons/cardengine/animation/animation_sequence.gd source), the position sequence, the scale sequence and the rotation sequence. Sequences are an ordered list of steps (AnimationStep class:
res://addons/cardengine/animation/animation_step.gd source). A step is composed of value (StepValue class:
res://addons/cardengine/animation/step_value.gd source) and a transition (StepTransition class:
Hopefully, you don't need a deep understanding of what all these classes do. CardEngine has a UI to edit animations, see below.
But first, it is important to understand how the animation chain works. The chain property comes from the fact that the start of one block is dependent of how the previous block ended. The chain is built has follow:
- Idle loop: this animation block is played in a loop when the card is not interacted with. It starts and stops at the origin.
- Focused animation: this animation block is played once when the mouse enter the card area. It starts at the origin and stops at its last step.
- Activated animation: this animation block is played once when the mouse is pressed. It starts at the last step of the focused animation and stops at its last step.
- Deactivated animation: this animation block is played once when the mouse is released. It starts at the last step of the activated animation and stops at the last step of the focused animation.
- Unfocused animation: this animation block is played once when the mouse exit the card area. It starts at the last step of the focused animation and stops at the origin. At this point, when this animation block finishes, the chain returns to the idle loop.
Each block, and each sequence of each block, is optional. Note that if there is no focused animation block/sequence the last step is the origin, the same for the activated animation block/sequence.
To create an animation press the "Create animation" button. Fill in the ID and the name. The ID cannot contain spaces, can only contain a-z A-Z 0-9 characters and cannot start with a number. The name can be any non-empty string of characters.
Changing ID and name
The ID cannot be changed.
The name can be changed by pressing the "Edit animation" button.
You can have a preview of your animation at any moment, even before saving, by pressing the "Preview animation" button. A dialog window will appear with a card playing your animation in the middle. You can use your mouse to go through the animation chain.
You can save your animation by pressing the "Save animation" button.
Important: no modification will be saved until your press this button.
If you made unwanted change that are still not saved, you can press the "Reset animation" button to return to the previous saved version.
To delete an animation, select it in the list and press the "Delete animation" button. You will have to validate the delete with the confirm dialog. Be careful, deleting an animation is not reversible.
To start editing your animation, first choose the animation block you want to edit. You will be presented with the 3 empty columns, 1 for each sequence. You can initialize the sequence you want to use by pressing the "Initialize" button in the corresponding column. Depending on the selected animation block, the initial sequence varies. Usually a sequence starts at an initial value, and stops at another initial value, that cannot be changed or removed. The actual value of the initial value, and the presence of an initial value at the end, is depending on where the block is in the chain. The starting and ending initial values can be different also.
You can add as many steps as you want with the "Add step" button. Tips: don't make your animations too long to avoid the feeling of a sluggish UI. The "Clear sequence" button removes every steps in the sequence, including those that are not removable individually.
Each line represents a step. Each step has two main buttons, except for the step 0, the left button is to change the transition and the right the value. Each step is followed by 4 tool buttons. The "▲" and "▼" buttons allow you to change the order of the steps by moving them up and down. The "D" button is for duplicating the step, which is added at the end of the sequence, but before the initial value if present. The "X" button deletes the step, deleting a step is not reversible.
A transition helps you smooth out the change of values between the previous step and this step, over a given duration. You can activate the "Random duration" so a random duration will be picked between a minimum and a maximum. You can change the duration in milliseconds with "Duration". With "Type" and "Easing" you control the smoothing curve (see here for reference). Additional features are available for creating more complex animations. You can tell CardEngine to flip the card at the end of the transition. You can disable interactivity during a transition if you want a step to go through no matter the input from the player.
A value defines the state you want your step to reach at the end of the transition. There is 3 modes to define a value:
- Initial: tell the step to go back to the initial value as defined by the position of the block in the chain
- Fixed: tell the step to use the given value
- Random: tell the step to use a random value between a given minimum and maximum
With "Value" you defined the value for the "Fixed" mode or the minimum for the "Random" mode.
With "Range" you defined the maximum for the "Random" mode.
Note: values are relative to the values defined by the layout.