About this manual
This manual explains the “Sprite Animation” tab and the “Collision Animation” tab in Maker mode’s object editing view. The first builds the frame layout (which image is shown for how many frames, and how fast); the second moves collisions and images in time with those frames. Detail work such as “only enable the attack collision at the moment the swing lands” or “bob the body up and down while walking” is built by going back and forth between the two.
What the three tabs each decide
There are three tabs in the centre of the object editing view. They are just different ways of looking at the same object, so fixing something on any of them ends up in the one object.
| Tab | What it decides |
|---|---|
| Preview | The base values of the collisions and images (the plain position and size, belonging to no animation) |
| Sprite Animation | The frame layout (the order of the images, the speed, looping) |
| Collision Animation | The per-frame values (the position, size and enabled state at a given time in a given animation) |
What you set on “Preview” is the foundation, and “Collision Animation” overrides it. If you want the attack collision always in the same place, Preview alone is enough; if you want it pushed forward only on the third frame of the swing, you put a key on the Collision Animation tab.
The selected animation carries across the tabs. Pick “attack” on Sprite Animation and move to Collision Animation, and you are editing “attack”'s collisions straight away.
How the data is held
In one sentence, the mechanism is:
- The frame layout’s master copy is the AnimatedSprite2D’s SpriteFrames. The Sprite Animation tab edits that.
- Every time you edit it, only the frame-advance track of the same-named animation on the AnimationPlayer is regenerated.
- Keys put down on the Collision Animation tab are not part of that regeneration. Changing the frame layout never deletes collision keys.
Because of this, it does not matter which tab you start editing from.
The Sprite Animation tab
Setting up for the first time
On an object that lacks the nodes animation needs (an AnimationPlayer and an AnimatedSprite2D), the tab shows a notice and a button.
| Button shown | When it appears |
|---|---|
| Use sprite animation (create AnimationPlayer + AnimatedSprite2D) | When neither exists |
| Convert Sprite2D to AnimatedSprite2D and use sprite animation | When the object was built with a Sprite2D in Godot mode |
| Load from template (setup + register animations) | When you want to set up and bulk-register at the same time |
The conversion carries the node name over. Since AnimationPlayer tracks resolve their target by node name, existing animations go on living. The image, placement and frame layout (hframes / vframes, or the frame-advance keys) are carried over as well.
This tab cannot be used on objects that use bone animation (Skeleton2D). The frame-layout mechanism does not fit, so you only get a notice.
Animation sets and animations
The left pane is two levels: “Animation Set > animation”.
- An animation set is the name of a grouping such as “idle”, “walk” or “attack”.
- Underneath it sit the animations per direction (the downward walk, the rightward walk, and so on).
- The end of each row shows the frame count.
What you can choose in the visual script’s “change animation” is the animation set name, not the animation name. For that reason, an animation that is not on a set cannot be chosen from the visual script. Adding an animation from the tab’s button also creates a set with the same name, so normally you do not have to think about it.
Animations that are on no set appear under “Unassigned” at the end of the list. That is so opening an older project shows them as-is without rewriting data; from there you can drag them into a set.
On objects that cannot have animation sets (effects, particles) the list is flat rather than two levels. An effect holds just one animation, and it is also set as the AnimationPlayer’s autoplay automatically.
What you can do in the list
| Action | How |
|---|---|
| Add an animation | The add button on the toolbar (an animation set with the same name is created too) |
| Add to an existing set | The “+” that appears on the set’s row |
| Duplicate | The duplicate button, or Ctrl+D |
| Copy / paste | Ctrl+C / Ctrl+V (it pastes into the selected animation set) |
| Rename | F2, or right-click → “Rename” |
| Delete | Delete, or right-click → “Delete” |
| Move to a set / take off a set / reorder sets | Drag within the list |
Copy carries the frame contents too. You can paste even after switching to a different object.
Deleting an animation set row also deletes the animations only that set uses. Animations referenced by other sets as well are kept. The tooltip tells you what the currently selected row will remove.
Setting the direction
Select a direction entry and the “Direction” 3×3 grid and “Auto Y Flip” appear on the right.
- The grid buttons specify which directions this animation plays for (you can pick several).
- Turn on “Auto Y Flip” and you prepare only the right-facing art; when the object faces left, the engine mirrors it.
- The default for a newly created animation is all 8 directions on a top-view project, and left / right on a side-view one (both assuming Auto Y Flip).
Rows in the list show the direction as an icon and text. Common combinations such as “all directions” and “left / right” are shown as one word.
Adding frames (Add from sheet)
“Add from sheet” cuts frames out of a sprite sheet.
- Pick an image (with “Browse”, or from the image list shown inside the dialog).
- Enter either the frame size (how big one frame is) or the horizontal / vertical frame counts. Moving one updates the other.
- Click (or drag) the cells you want on the grid. “Select All” and “Clear” are there too.
- Tick “Loop” if you need it, then add.
- Replacing the image re-measures the frame size against it. If the current frame size divides the image evenly, the division is kept; on an image it does not divide evenly (48×40 while set to 32×32, say) one frame becomes the whole image.
- The grid’s zoom can be changed.
Ctrl+ wheel also steps it up and down. - “Adjust initial collisions” opens a separate window that adjusts the existing collisions using the selected frame as the reference. What you adjust there is applied not only to the base values but also to collision keys already put down in that animation (because if a key holds an old value, changing only the base value would not change what you see).
- One animation can mix frames from several sheets.
Dropping an image onto the playback preview also opens “Add from sheet”. Drop from the image list dock and it opens with that image loaded. If there is not a single animation yet, you are asked whether to create one first.
Adjusting the frame layout
You adjust it with the strip of frames at the bottom and the toolbar above it.
| Item | What it is |
|---|---|
| FPS | The speed of the whole animation (1–120, default 8) |
| Loop | Do Not Loop / Loop / Ping-Pong (ping-pong runs to the end then plays back in reverse) |
| Wait (multiplier) | The display-time multiplier for the selected frame only (0.01–10; at 2 it is shown twice as long as the others) |
| Zoom | The playback preview’s zoom (Auto / 50% / 100% / 200% / 400% / 800%) |
- Frames can be reordered by dragging. There are also buttons to move them left and right.
- Frames can also be removed with
Delete. - The play button runs the preview. An animation that does not loop stops on its last frame, so you can check how it finishes.
The “Auto” zoom can land on an awkward magnification for pixel art. When you want to check how it really looks, fix it at 100% or 200%.
Load from template
“Load from template” uses a template sheet to bulk-register animations and animation sets.
- For top-down view (RPG Maker format): registers 4 directions × walk / run / idle / stop (and attack) in one go, including assigning the animation sets. The weapon image for attack motions is supported too.
- For side view: registers following the template’s row order, with Auto Y Flip so left and right both work.
Both finish as a single operation (a single undo). On an object that has not been set up yet, the required nodes are created as part of the same operation.
For the exact formats, see the separate manual “Load from template”.
The Collision Animation tab
The tab for moving collisions and images per time in step with the frames. You pick the target element on the left, move it with the handles on the preview, and register it as a key.
What can be moved
Pick it from the “Element” list on the left. What can be moved differs by kind of element.
| Element | What can be moved |
|---|---|
| Object body (purple) | Rotation / scale |
| Object image (white) | Position / offset / rotation / scale / visibility |
| Wall collision (cyan), hit collision (blue), attack collision (red) | Enabled state / position / rotation / scale / size (radius and height, depending on the shape) |
| Connector | Position |
- The body has no position. The root’s position is rewritten by the movement processing at runtime, so a key on it would be meaningless.
- Only when the image is a Sprite2D can “frame number”, “flip H” and “flip V” also be moved. An AnimatedSprite2D’s frame number is under the Sprite Animation tab’s management, so it is excluded.
Switching which elements are shown
Right-click an empty part of the list to choose which kinds are shown. The setting is remembered per project.
“Object body” is hidden by default. Settings that rotate the body do not coexist with horizontal flipping (Auto Y Flip), so it is left for those who know to bring out themselves, to prevent accidents. While something is hidden, a mark appears on the heading.
Simple mode (the default)
The mode for editing per frame.
- Pick the frame you want to edit from the frame list shown below the preview.
- Drag the handles on the preview to change the position or size.
- The change is registered onto the selected frame automatically.
- Keys are put at the start time of the frame. A key can never end up mid-frame.
- On the preview, wheel = zoom and middle-drag = pan.
- At the end of the frame list there is an “END” row. That is not an actual frame but a row pointing at the end of the animation (the loop’s seam). When you want a value in the stretch “from the last frame back to the first” — a full 360-degree rotation, say — you put the key here.
- If no frame list appears, that animation has no frame-number track (or no frames). Edit it in Detailed mode.
Detailed mode
The mode for specifying times freely. Get there with “Switch to Detailed mode”.
- Timeline key editing is done on the standard AnimationPlayer panel at the bottom (opening the tab switches it to the target player and animation automatically).
- Seek on the timeline and adjust with the handles on the preview.
- Leave “Auto Sync” on and a key is registered at the current time the moment you release a drag. With it off, you put keys down with “Register the current state as a key”.
- While this tab is open, the cut / copy / paste shortcuts for keys (
Ctrl+X/C/V) are disabled. That is to prevent mistakes right after clicking the timeline. Explicit operations from the menu still work. - Switch the animation on the bottom panel and the list on the left and the preview follow.
The toolbar buttons
| Button | What it does |
|---|---|
| + Add Track | Adds tracks for the selected element to this animation |
| Register the current state as a key | Inserts the selected element’s current values as a key at the current time (missing tracks are added automatically and you are told so) |
| Auto Sync | Registers a key automatically when a drag is released (Detailed mode) |
| Sync initial key | Applies the collision values set on the Preview tab to the 0-second point |
| Reset to origin | Returns the selected element’s position to (0, 0) |
| Interpolation | Changes the interpolation of the selected element’s numeric tracks together |
| Snap to grid / snap interval | Snaps position and size to multiples of the given pixel value while dragging |
| Play | Plays the preview inside the tab |
About “Sync initial key”
The key at 0 seconds is treated as the “base value”. Press the button and the values set on the Preview tab go into the 0-second point of the animation you are editing, and tracks for collisions that no longer exist are removed.
This is the fix for “I tidied up the collisions on Preview, but playing the animation puts them back in the old place”. Conversely, keys you deliberately put down mid-frame are left alone.
Note also that when you change a base value on the Preview tab or in the Inspector, the 0-second key follows automatically. Without that, saving the scene would put the old value back (because the base-value animation is applied to the node at save time).
Interpolation
| Mode | The movement |
|---|---|
| Discrete (per frame) | The value jumps at the moment the frame changes |
| Continuous (smooth) | The gap between keys is interpolated, so it moves smoothly |
| Mixed | The state where tracks have different settings (display only) |
The default for newly created tracks is “continuous” for images and the body, and “discrete” for collisions. Collisions are mostly used as “enabled only during this frame”, and interpolation would create unintended in-between states. If the existing tracks all agree, that setting is inherited instead.
With bone animation
On objects that use bone animation (Skeleton2D), the preview cannot show the art (this tab’s preview is hand-drawn, so it cannot reproduce bone deformation). You only get a one-line notice at the top, and placing collisions still works.
How the two tabs work together
Keys following a changed frame layout
Keys put down in Collision Animation are saved at absolute times. So if you change the FPS or a Wait on the Sprite Animation side, or add, remove or reorder frames, the correspondence between frames and keys would break if nothing were done.
It is handled automatically.
- The layout before and after the edit are compared, and key times move to the position of the new frame.
- Keys that were in the stretch of a deleted frame are deleted with it.
- Keys at 0 seconds (base-value keys) always stay at 0 seconds.
Ctrl+Zreturns both the frame layout and the keys.
How base values are distributed to every animation
When you create a track, a base-value key is put at the 0-second point automatically, and it is distributed to the start of every animation. That means values you moved in a previous animation do not linger when the game switches animations.
Worked examples
Enabling the attack collision only on the third frame of the swing
- On the “Preview” tab, tidy up the attack collision’s position and size (this becomes the base value).
- On the “Sprite Animation” tab, pick the attack animation and settle the frame layout.
- Move to the “Collision Animation” tab and pick the attack collision from the elements.
- Pick frame 1 in the frame list, set “enabled” to disabled and register the key.
- Pick frame 3 and enable it, then disable it again on frame 4.
- Play it back and check that the collision only appears on the frames you wanted.
If the collision does not appear where you expected, press “Sync initial key” and try again. A key with an old value may be sitting at 0 seconds.
Bobbing the body in time with the walk
- On the “Collision Animation” tab, pick the object image from the elements.
- Pick a frame in the frame list and drag it up a little on the preview (the change is registered onto the selected frame automatically).
- Drag it down on another frame.
- Set the interpolation to “Continuous (smooth)” and the gaps between frames are interpolated smoothly.
Building a full 360-degree rotation
- On the “Collision Animation” tab, make object body visible (right-click the empty part of the element list).
- Put a key of 0 degrees on the first frame.
- Pick the “END” row at the end of the frame list and put a key of 360 degrees there.
Putting it on the last frame makes it look like it rotates backwards in the stretch from there back to the first frame. END is the right place.
Making a character from right-facing art only
- Create the right-facing animation on the “Sprite Animation” tab.
- Pick the direction entry and specify “right” on the 3×3 grid.
- Turn on “Auto Y Flip”. Facing left is mirrored automatically.
Things to watch out for
- An animation that is not on an animation set cannot be chosen from the visual script. The candidates in the visual script’s selector are built from animation set names, not animation names. Drag anything left in “Unassigned” into a set.
- Deleting an animation set row also deletes the animations only that set uses. Ones referenced by other sets as well are kept.
- “Ping-Pong” cannot be expressed on the sprite animation side alone. The data structure there can only hold whether it loops, so ping-pong is saved as an animation-side setting (you do not have to think about it while working).
- Changing the frame layout moves collision key times, and keys in the stretch of a deleted frame are removed. On frames that hold keys you want to keep, adjust with Wait instead of deleting.
- The key at 0 seconds gets special treatment as the “base value”. It is distributed to the start of every animation and applied to the node when the scene is saved. Putting a value for presentation there affects the other animations too.
- If collisions you tidied up on the Preview tab revert in an animation, press “Sync initial key”. The 0-second key is holding the old value.
- “Object body” does not coexist with horizontal flipping (Auto Y Flip). That is why it is hidden by default.
- The default interpolation for collision tracks is “discrete”. Change collisions you want to move smoothly to “continuous” explicitly.
- Objects that use bone animation (Skeleton2D) cannot use the Sprite Animation tab. The Collision Animation tab works apart from the preview not showing the art.
- An AnimatedSprite2D’s frame number cannot be moved in Collision Animation. The frame layout is under the Sprite Animation tab’s management as the master copy (only on objects built with a Sprite2D can the frame number be specified in Collision Animation).
- While Detailed mode is open, key operations via
Ctrl+X/C/Vare disabled. They are still available from the menu.