Toon Boom Jump Tutorial: Adventure Platformer
Player State Machine Presentation
Animation Player Manipulating States Parameters
Animation Mappings for the Player
Idle Animation Configured for Both Directions
Adventure platformers, also know as metroidvanias, are platformer games with additional actions besides run and jump. Games in this category are complex and usually contain several distinct mechanisms for the scene and the enemies.
There is one common element among all of them: the player character must be able to perform several actions such as run, jump, double jump, attack, hang, slide, and crouch.
The game development field devised a pattern to help the development of controlling the actions.
Using a finite state machine, the input can direct the character from the current state to a valid one with little effort.
This tutorial will cover the process of configuring the character Perry Poireau to act according to most player actions.
Creating the Project
To begin configuring the Adventure Platformer template:
-
In the Jump homepage, select the Adventure Platformer template and fill in the following:
-
Project Name
-
Game Description
For this tutorial:
-
Set the Project Name as “Adventure Platformer Starter Pack”
-
Set the Game Description as “Preparing for the Journey"
-
The library already has the Perry Poireau asset.
Inspect the Animations
First, ensure that the asset is ready for the game engine before exporting. You can do it from the Asset Editor to check what animations are available and possibly fix some.
Double-click on the PerryPoireau_PointClick to open it on the editor. In the Asset Editor you can check each animation.
The animations are on the Scene Markers panel. Each Scene Marker is exported as an animation. You can select each one and click on the Play button to make it run.
If you prefer, click on the Loop button. This way, when changing the animation, the selected one will start as soon as the other finishes and it will be easier to evaluate.
Running the Project
Open the game engine and wait for the assets to be imported.
The Adventure Platformer template has only one stage, which is a sandbox for testing the character configuration.
If you run the project, you will see that the character moves, and that it hang on ledges and climb them. However, the character is static and there is no animation. This will need to be configured.
Player State Machine Presentation
State Machine is the mechanism to control the transitions for several actions the character can do.
Open the player scene. The scene from the TBG asset is used as a resource for our player scene. Use as a graphical resource means calling the asset’s animation and setting other structures to control the game mechanics.
The state machine is the node we want to evaluate. It is a simple node and does not even have a spatial component. It is used only to manage the character state.
The code is simple. It has an initial state, the current state, and a dictionary of states. The main function is the transition, which will call the current state to exit, set the current state, and call the enter method on the current state.
Idle State
The finite state machine mechanism means the behaviour related to each state is coded in each state node. The state machine’s initial state is the idle state.
The idle state looks for the attack event, calling the state machine to transition to two possible states upon the “attack” action. Depending on the player's sword status, that would be the “draw” state or the “attack” state.
Other possible transitions occur on the state_check function, and it can transition to the slide, crouch, crouch_walk, run; jump_top, jump_fall, or jump states.
There is a function that transitions to the sheath state as well. The state_check is called on the engine processing loop, but the sheath function is called when the timer configured in the enter routine runs out. The timer is only configured if the player has the sword active.
The enter routine also sets the animation for the state. The animations are always set on the states’ enter method.
Exiting the idle state only calls to disconnect the timer and stop it.
Run State
The Run state transitions when the player's direction is not zero, meaning when the player moves.
The Run state has the same input treatment as the Idle state.
Animation Player Manipulating States Parameters
The state_check is always called on the game process loop, and it sets the animation upon entering. On the state_check, the transitions are based on the player status, and the exit routine is void.
This process is the pattern for the StateMachine states behaviour.
And here is where the Player script and the AnimationPlayer node enter.
Upon opening the AnimationPlayer, it is possible to investigate some animation properties.
Some animations call routines and other changes values on the StateMachine states nodes.
Configuring Climb State
The climb animation has two tracks. The track for the climb state is the one we want to check. It manipulates a property called climb.
The climb property, manipulates the player's position. This process is interesting because the player position can be managed indirectly. In this case, it can be managed via the climb property on the climb state.
Animation Mappings for the Player
The Player script has an asset already assigned to it, the Perry Poireau. You can also set a different asset to it by dragging the TBG-derived .tscn from the FileSystem to the Tbg Asset property in the Inspector.
The automatic mapping takes place on the _ready function. It resets the animations in the AnimationPlayer and connects the animation from the TBG asset to the animation player.
However, you need to configure your TBG asset first.
On the script top, after the properties declaration, there is a dictionary of animation maps. Although you can type the animation you configured on your TBG asset in the related key value field, it is advisable to name the animation as the key in the map when configuring.
Idle Animation Configured for Both Directions
Note that you don’t need to map all the animations. The animations that have no mapping will default to the idle animation.
Now you can configure the idle animation and run the project.
Note that the behaviour is similar to the first run since it only has the idle animation running.
Hanging on a Ledge
Now, configure another animation for when the character hangs on a ledge.
Going through the character animations, we see that the slide horizontal is the one we want.
The animation name in the editor does not need to be changed. Its name can be set here.
But it has no “hanging” or other in the list we need to create. And we need to create with the same name as in the mapping.
Looking at the map keys, you can see the “hang” key. That is the one that makes sense for what you want to do.
Go back to the Toon Boom asset window and edit it.
Select the animation for the one you want to map. If it is not selected already, click on the pencil, type “hang”, and click the green tick button. Set the Facing to the Right, and on the motion menu, click Create Flipped Permutations to create the flipped permutations.
Now, run the project.
The character is still with the idle animation, but it hangs when it goes to the ledge. If you press up, it slides up and you get control again.
However, there are no animations for climbing or walking. In the animation map list, it is “run”, not “walk”.
All you need to do is configure your asset with the animation maps in mind, and everything will work as expected for the animations. Now, run it check the result.
You can look at the animation map list to know what animations are available.
Not all animations are available. There is only one attack, and there are lots on the list. There are even some in the air. Those have not configured. Their state will be called, but since the animation is not Run, it will transition as quickly as possible to the next as if they were never called.
To illustrate the state parameterization via animation player, click on the AnimationPlayer and select the Climb animation.
Change the last key value for the y parameter to 90.
Now, Run the project and try to climb the ledge.
Last Key Value
Let’s do the opposite! Change the last key value for the y parameter to 300 and run again!
See any difference? The parameters you changed are passed to the state object. The state object, if it is the current state of the machine, has code that will influence the player considering that state logic behavior.
To remember:
-
Configure your asset animations having the animation maps in mind.
-
Drag your asset to the TBG asset property of the player scene.
-
Configure extra properties in the animation player animation with the same name as the state.
Now your character setup is ready to be played. If you want to change the level or create a new one, look at the Simple Platformer tutorial and Godot’s TileMap node documentation to improve your design.