This page will guide you on the way animations work on Pikifen, and how to make your own.
An animation is a collection of images that flip in quick succession to give the illusion of movement. For instance, for a Pikmin's attack animation, it would consist of an image (also called a frame or a sprite) with the Pikmin clinging on, an image with it reeling its head back, an image with it swinging the head forward, and an image where the stem shows recoil from impacting something. By quickly flipping through these images, it gives the illusion that the Pikmin is moving.
On the engine, every object has a list of animations. Animations are made up of frames, an in the engine, each frame fetches information from a sprite. This is because, in order to save on space, an animation may reuse the same image multiple times. In the example of the Bulborb on the right, the "half-step right" image (#2) is used both after and before the "full-step right" image (#3). As such, there is only one sprite for the "half-step right", and two frames in the walking animation that make use of that same sprite.
Finally, each object also has a list of body parts. In each sprite, you can place different hitboxes (also known as hitbubbles), with each one matching a body part. This way, if a Pikmin is clinging on to the Bulborb's "back", the engine will know where the place the Pikmin at any moment, since the creature's back changes places during its animations. The fact that each body part is also represented by a hitbox means you can specify if that body part can be damaged, latched-on to, or if its currently attacking or knocking Pikmin away, among other things.
Starting some animations
Before beginning to animate an object, you must have that object on the game's data (see the object types tutorial), as well as some images to be used as the sprites. In order to be consistent with the style, the images should be in a top-down perspective. Each image must also show the object facing the right. Although it is possible to place each image in a different file, it is a lot more efficient to have all (or most) images for the object within the same file, separated by a grid. These are what is known as "spritesheets". For examples, see the spritesheets that come with the engine.
If your enemy is completely new, you will have to create the images from scratch, or download them off somewhere. If your image is a recolor of an existing one, you can make a copy of the original enemy's spritesheet and use any painting program to change the colors. You can also use the SVG files used on the prepackaged enemy graphics with a vectorial art editing program to change the color schemes.
Using the animation editor
On the engine, open the animation editor. On the left side of the editor, you'll see an empty canvas. This area will show what the sprites and animations look like. On the right side, there is a panel, where you perform most of your tasks. Below that panel is a smaller panel with a button to toggle hitbox visibility (plus the grid that aims to the center), load the animations from the game files, save the animations to the game files, and exit the editor. Finally, to the bottom-left is a status bar that will give you information about anything you place your mouse cursor over on the panel, so use that if you need help.
For the sake of this tutorial, we'll be creating the animations for a Red Bulborb, using the prepackaged Red Bulborb spritesheet. For that, you should probably create a new Red Bulborb enemy, as you don't want to work on top of the existing enemy's animations; we're doing things from scratch.
Pick the file for your enemy's animations, which must be called
Animations.txt, and likely in the
/Game_data/Types/Enemies/<the new enemy's name> folder. After you load the file, some buttons and statistics will appear. Let's begin by creating the enemy's body parts.
Creating a body part
From the main panel, click "Edit body parts", so that you may enter the body part control panel. Some instructions appear on the top-right. There should be no body parts, so let's use the textbox on the panel to type the name of a new one. But first, let's think about what body parts this enemy will need. Body parts are circles, and because the Bulborb is a very round creature, we could use a bubble for its entire body and call it a day. But it is also true that hitting a Bulborb on its back causes more damage than the front. So we'll need to distinguish between the head and the back. Finally, the Bulborb can grab Pikmin with its mouth, and the engine must be able to recognize the mouth as a body part that can capture Pikmin.
Let's start with the simplest one: the head. Type
head on the textbox, and press the nearby "+" button. This will register the first hitbox. Then do the same for "back", and once that is done, do it for "mouth". There, now the body parts that we'll be needing are all registered. Oh, but there is something else we need to think about here. Because the hitboxes are bubbles, it will be nearly impossible to align them on the Bulborb without them overlapping, unless we leave a huge chunk of the enemy uncovered by hitboxes. What happens if a Pikmin hits both the "back" and the "head" hitboxes, because they intersected? How will the engine know which one to connect the Pikmin to? This is where the note on the panel comes into play. The lower the number of a hitbox, the higher its priority for scenarios like that one.
We will want the player to benefit from the extra damage bonus as much as possible, so it's fair that the back hitbox has higher priority when it comes to being picked in the case of a tie. But the order we currently have is the head as #1 and the back as #2 (you can use the < and > arrow buttons to switch which hitbox's data you're looking at). We can move the back to the previous number by pressing the "<=" button. The arrows may be a bit confusing, but remember that the status bar on the bottom-left can explain what they do so long as you place your mouse over them.
Creating a sprite
You can now press the "Back" button to return to the main panel. From here, enter the "Edit sprites" mode so we may create our first sprite to be used in some frame in the future. Begin by pressing the "Sprite" button at the top of the panel. This will give you a list so you can choose which sprite is it that you are editing, but because there are none, the list will be empty. There is however a textbox at the top which you can use to create a new one. Just give it a name. Let's start with the most basic pose, which would be the idle position. Type "idle" for the name of this frame.
A fair bit of information just got unlocked, and a green bubble appeared on the center of the canvas. If you can't see the bubbles, click the "Hitbox visibility" button on the bottom-right. Either way, ignore the bubble for now. We will need to specify in what file the image for this frame can be found in. For that, we use the "File" textbox. The file should be located on the "Game_data/Graphics" folder, and when writing the name, you should include the extension. To use the pre-packaged Red Bulborb spritesheet, type
Red_Bulborb.png into the box. Now, we need to tell the engine where in the spritesheet our "idle" sprite is. On the pre-packaged spritesheet, this is the one on the top-left. For the "File XY" textboxes, we will specify the coordinates of the top-left point of the sprite. For this pose, they're in the top-left corner, so both X and Y are 0. You can use a painting program like Paint or GIMP to check the coordinates of a point in an image. Now, we will tell the engine the size of this sprite on the spritesheet. The pose in question, on the pre-packaged sheet, is 153 pixels in width, and 103 in height, so type those values onto the "File WH" textboxes.
The engine has now successfully captured the image from within the spritesheet, and we should see the Bulborb on the main window. You'll notice how the editor automatically filled in the "Game WH" fields based on what you typed. In general, the sprites should be made so that one pixel in the image corresponds to one unit in the game world, which means that the in-game dimensions are normally the same as the in-file dimensions. This is true for the pre-packaged Red Bulborb, so leave those boxes alone. But things like leaders and Pikmin use higher quality images, which means that the in-game dimensions cannot be the same, otherwise they would show up huge. Plus, a Dwarf Red Bulborb uses the same spritesheet as a Red Bulborb, but in-game, the graphics are much smaller, so the "Game WH" fields are changed to something smaller.
Although some enemies have the center of their sprites match the center of their body, this is not quite the case for the Red Bulborb, as it makes more sense to consider the center of its body as the center of its backside; basically, when the creature rotates, it does so around this point. (You reach conclusions like these by trial-and-error, so don't worry that you didn't think the same.) The white plus-shaped grid indicates where the center of the object is. In order to align the sprite, we will use the "Offset" textboxes. To align this sprite of the Red Bulborb, simply type 16 for the X offset, but different sprites might require different measurements. Feel free to type the "Offset" button to launch a wizard that helps you align it better; this allows you to use the mouse instead of typing numbers, and allows you to compare the current sprite with an existing one.
Our frame is now good to be used in an animation, except the hitboxes are all crumpled up. That's right – the green bubble in the center of the sprite is the three hitboxes we created, all occupying the same spot. Click the "Edit hitboxes" button on the frame data panel. The bubble will receive a gentle glow, to let you know that it is currently selected. You can see which hitbox this is by checking the name on the top-right of the panel. To select a different hitbox, either click on it, or use the "<" and ">" buttons. We can move a hitbox by clicking on its center, and dragging it with the left mouse button. In order to clean up the workspace so we can get a better view on how to organize the hitboxes, drag the three hitboxes away from one another. Now, let's take care of each one, one at a time.
Of the three hitboxes, pick the one corresponding to the Bulborb's back, which we named "back". Use your mouse to place it on the Bulborb's back. You should see the X and Y textboxes update as you move it around, meaning you can either position a hitbox using the mouse, or those textboxes. Now, you may have noticed that the hitbox doesn't cover up the creature's back that well. That's because the hitbox is using the default size of 32, and we're meant to change sizes as we see fit. To change a hitbox's size, you can either edit the "Radius" textbox, or grab the perimeter of the hitbox and drag it around with the left mouse button. With a radius of 50, the hitbox fits the Bulborb's backside just fine, so simply drag it into place after you're done changing its size.
Before we move on, we need to specify something else: the Z and the height. Just like the X and Y coordinates control where the hitbox is in space, so does the Z coordinate controls where it is vertically. Imagine the hitboxes as cylinders. 0 means it starts at ground level, and higher values make it float off the ground. For most enemies, you can keep it simple and leave all hitboxes to start at ground level, but if you want to create, say, a Beady Long Legs, the body's hitbox will need to be above ground, and this is where you'd change it. The height, on the other hand, is more. If the height is 0, that means the hitbox has no size, and will not work. So, we must set its height so that the Pikmin, leaders, etc. may interact with it nicely. For most cases, the Bulborb included, we can once again keep it simple: simply write on this height the exact same height that the Red Bulborb object has, which should be 128. In-game, everything will look good enough, but if you wanted an unnecessary level of realism, you would need to write more specific heights for each body part (for instance, the Bulborb's mouth is not as tall as its whole body, and starts higher above the ground).
Now that the "back" hitbox's positioning is all set up, let's change how it works for combat. There are three radio buttons labeled as the "Hitbox type". Bulborbs can't attack with their backsides when idling, and their backs are definitely present when on the "idle" pose, so it's neither an attack nor a disabled hitbox. So, the hitbox type to pick here is "Normal". Remember how the backside is meant to suffer extra damage from Pikmin attacks? We can set that on the defense multiplier. "1" means that hitbox has a defense of 100%, so it takes full damage, while "0.8" means the hitbox only has 80% defense, meaning it takes a bit more damage than normal. "0.8" seems like a good value for this hitbox, but lower than that could start to make the backside too weak. Remember to experiment when creating your own enemies. Before we move on to the next hitbox, check the "Pikmin can latch" checkbox because Pikmin are indeed meant to latch on to a Bulborb's back.
Now, do the same for the head hitbox. As was stated before, it will be next to impossible to place the hitboxes such that they don't overlap or leave parts of the enemy uncovered, so try to go for a good balance between the two. Make the hitbox cover the parts of the head that the "back" hitbox doesn't cover, but don't make it too big, otherwise Pikmin will be able to latch on and hit the air. Likewise, don't make it too small, or else Pikmin will not be able to grab a part of the Bulborb that should seemingly be grabbed. Try these coordinates: 52 and 0 for the X and Y, and 40 for the radius. This is more or less how the hitboxes should be placed: they cover everything with a good balance. Remember to also fill in the hitbox's Z (still simple, so still ground level, so still 0) and height (still the height of the Bulborb, 128), the hitbox type (also normal), and specify that Pikmin can latch on to it. You should leave the defense multiplier as 1.0, as it makes sense for the head to take a normal amount of damage.
Finally, let's move on to the mouth. This is the body part that will be able to hold captured Pikmin, so don't make it too big nor too small. A radius of 16 for this is enough. Place it on the general area of the mouth. Fill in the other stats as usual. Now, do we really want the Pikmin to be able to attack the mouth? It's a body part like any other, but it might make things a bit more complex to keep the mouth around, especially considering that it's so small, and the bulk of the damage collisions happen on the creature's back and head. As such, change this hitbox's type to "disabled", meaning that, in an "idle" pose of whatever animation, the engine will not have to worry about its mouth. Of course, it will worry about the mouth on some other frames, just not here. But...why bother placing it in the first place? This is so that if the "eating" animation needs to use this sprite, the engine will know where to place the Pikmin in the creature's mouth.
Let's create the rest of the sprites for the walking animation. If you didn't notice, the "idle" frame is part of the walking animation. The idle pose is the Bulborb posing still in a neutral position, but to walk, it lifts its right leg, returns to the neutral position, lifts the left, returns to neutral. For most enemies, the "idle" frame is actually used quite a lot. To create the sprites that will make up the rest of the walking animation's frames (walkl1, walkl2, walkr1, walkr2), check the Red Bulborb that comes with the engine. You can also copy and paste from the Animations.txt files. One thing to note is that "walkr1" is just "walkl1" except flipped vertically. You can obtain this effect by specifying a negative height (negative width obviously means flipping horizontally).
Once you have those sprites, go to the main panel and enter the "Edit animations" mode. It should be empty, since there are no animations, but just like with the sprites, we can click the "Animation" button to create a new animation. For the walking animation, call it "walk". Ignore the "Loop frame" box for now. The frame list is a list of the frames that this animation is composed of; each one of these makes use of a sprite we created earlier. There is a button to play or pause the animation on the left side of the editor, a button to switch what frame you're currently looking at, a button to add a new frame, and a button to remove the current one from the list. Add the first one with the "+" button. On the "Sprite" button, choose "idle", making this the first frame of our walking animation. Next, we specify how long this frame exists for until it is replaced by the next one on the list. 0.1 or 0.2 is usually a good value.
Press "+" once again to add a new frame. This will be created using the same data as the previous frame, for convenience, which means you don't need to change the duration this time (unless you want to). The next frame in the animation would use the sprite "walkr1", and the one after would use "walkr2", then "walkr1" again, "idle", "walkl1", "walkl2", and "walkl1". It would make sense for the animation to loop back to the first "idle" frame so it repeats the same "right foot, left foot" cycle. This is where the "Loop frame" textbox from before is used. Luckily, it is already set at 1, which is the first frame, so you don't need to change it this time, but if you wanted the animation to repeat from a specific frame, this is where you'd write the frame's number. Feel free to play the animation with the "Play/Pause" button. As a reminder, you can also use the "Hitbox visibility" button on the bottom-right panel to disable the grid and the hitboxes, which will give you a better view of the creature itself.
When editing sprites for a Pikmin, you must specify where the Pikmin's top (leaf, bud, or flower) is to be located on that frame. For that, click the "Edit Pikmin top" button on the panel when editing a frame. You can then drag around with the left mouse button to move the top's positioning, but you can also set it with "X&Y" textboxes. You can set the dimensions of the top's image using the textboxes, or you can switch modes on the panel and use the left mouse button for that instead. Finally, you can also set the top's angle, and once again, change modes to rotate with the mouse button. If you would like to see how the Pikmin looks with a different object as its top, press the "Change maturity" button.
On some sprites, the top might not be visible whatsoever. For instance, when a Pikmin is thrown, on the frames where it is upside down, the top is under the Pikmin, so from a top-down view, it is impossible to see. For these cases, uncheck the "Visible" checkbox.
To create enemies, you can make whatever animations you wish, and you can call them whatever. As long as you use the correct names on the script, all is good. But for Pikmin, gates, and most other objects, the engine is the one that decides what animations to switch to, and it expects to find them with specific names on the object's animation data.
All object types need an
idling animation. This is the object in its most basic state: just sitting around doing nothing. For objects that have no real animation or choice on what to do, like a gate, this animation is important, as it represents its "usual" state. Besides the
idling animation, the following is a list of what animations exist for every object type.
thrown: Twirling in the air after being thrown.
attacking: Reeling back its head and smacking with it.
grabbing: Standing upright and grabbing onto an object.
sprout: Idling underground; only the stem is visible.
plucking: Coming out of the ground.
lying: Knocked down to the ground by an attack, staying there for a bit, and getting back up.
carrying: Carrying an object.
sighing: Sighing after becoming disappointed with something, like being unable to reach a carrying spot.
Note that Pikmin don't use hitboxes, so you don't need to create any. Also note that, on the frame in which a Pikmin's attack connects, you should include a "signal" on the signal textbox, like "0". This lets the engine know that when the Pikmin reaches this frame of animation, that an attack connected, and damage needs to be dealt.
getting_up: Getting up from lying down or from being knocked down.
dismissing: Dismissing the group.
throwing: Throwing a Pikmin or teammate.
lying: Lying down on their own accord (like the Napsack in Pikmin 2) and staying there.
pain: Reeling back their head in pain.
knocked_down: Knocked down to the ground by an attack, staying there for a bit, and getting back up.
spraying: Using a spray.
Note that leaders don't use hitboxes, so you don't need to create any.
Gates and bridges
destroyed: Nothing's there; this is after the obstacle is cleared.
Game_data/Animations contains a list of custom animations that aren't necessarily bound to an object. These can include animations expected by the engine, like the status effects or liquids.
- You can zoom in on the canvas by scrolling the mouse wheel, pan by holding the right mouse button, and reset the zoom and pan by clicking the mouse wheel.
- You can press Ctrl + Tab or Ctrl + Shift + Tab (Cmd instead of Ctrl on Mac) to go left and right between the current hitbox, frame, etc.
- Remember to save periodically. Although rare, it is possible for the editor to crash, causing you to lose unsaved progress.
- When making a spritesheet, try to add at least one row or column of empty pixels between each frame. Without this padding, some in-game sprites will have artifacts from a sprite right next to them.
- If your graphics are twice the resolution of your in-game size, you can enter the special tools from the main menu, and use the resolution resize tool. If they're twice as big, use the value "2" in this tool.
- If you accidentally named a sprite or an animation the wrong thing, you can enter the special tools from the main menu, and use the corresponding renaming tools.
- If you have an enemy shaking animation, and only want a percentage of the Pikmin to be shaken of, you can make the shake animation a "missable" attack animation. For instance, if you type in the textbox
70, that means only 70% of the Pikmin that are latched on will get knocked out, on average. This can be used for other attacks too, not just shaking. This feature only affects Pikmin, and does not apply to hitboxes with hazards.