Mot's Animation System
Mot's Animation System is a visual editor for creating 2D animations.
You start by sequencing sprites and/or tilemaps together to create the basic components. Then combine them using timelines and key-frames to make animations. Or combine them again to make bigger, more complex animations.
Animations can trigger sounds and music, and call back into to your main program, e.g. to trigger game play events.
You could use it for:
- Character animations, like run cycles
- Larger multi-sprite animated characters
- Animated birthday cards
Animations can be loaded and played in your own carts (the loading and playback code is 1836 tokens). They can either be stored in Lua strings or loaded from a separate cart.
This is all very much in Beta at the moment!. And some corners had to be cut to fit everything into the token limit. In particular the editor doesn't prevent you from shooting yourself in the foot by:
- Creating self referencing animations (infinite recursion)
- Creating animation files larger than 0x4300 bytes (about 17K) that won't save properly.
It lacks any sort of undo/redo logic, so if you use this, please take frequent backups of your saved animations.
And also, because the animation code is 1836 tokens and the animation data can be several kilobytes, it's not the best fit for every program.
Feel free to @ me if you need any help.
Overview and basic navigation
WARNING: While you can edit animations in the nested browser version you can't save them! So please don't get too invested if you play with it in-browser. Run it from Pico-8 itself in order to save your changes.
Selecting and playing animations
Move the mouse over the window to display the UI.
You can pan the animation with the middle mouse button, and zoom in/out with the scroll wheel.
At the bottom right there are 3 controls:
- A slider to zoom in/out (behaves exactly the same as the mouse wheel)
- A play/pause button that does what you'd expect
- A home (house) button recenters the animation and sets the scale back to 1
The name of the current animation is displayed at the top. Click on it to select another animation.
Use the mouse wheel to scroll through the animations. Animations with a person icon are sprite/tilemap animations. Animations with a dotted line icon are key frame based animations.
At the top right are the menu icons. Clicking on them opens a drop down menu.
The hamburger menu is for creating/deleting animations.
You can create new animations of different types, or delete the current animation.
The hourglass menu is for saving and loading animation sets.
You can save/load your animations to from external carts or import sprites and tilemaps from another cart.
This is covered in more detail later.
Click "Properties" at the bottom of the screen to expand the properties panel.
This is where you edit the current animation. The UI changes based on the animation type.
When expanded, the "Properties" bar also displays two icons. These toggle between different tabs.
The I icon displays information and settings for the animation. Once again they differ based on the animation type. The other icon will be the person or dotted line depending on the animation type, and switches back to the main editor.
(...and music and sound effects)
In order to create animations for your own carts, you'll want to import the sprites and tilemaps that your cart uses.
Click the hourglass icon at the top right, then select "IMPORT GFX". This will list the carts in your Pico-8 carts folder.
Once again you can scroll with the mouse wheel.
Click on the cart to import its sprites, tile maps, sound effects and music into the editor.
Select "Clear" from the hourglass menu to clear out the demo animations.
Saving and loading
The hourglass menu allows you to save and load your animations. Animations are saved to Pico-8 cartridges ("carts").
They overwrite the sprites in the cart, and possibly the tile maps, sfx and music, depending on how many animations you have defined. Therefore you should not save your animations into your existing game carts!
To avoid catastrophe the editor will only save/load animation data into cart files that end with .anim.p8
"Save", "Save as" and "Load" work as you would expect.
The first time you save (or if you click "Save as") you will be prompted with a list of animation carts to save into.
Or you can click "New Cart" and key in the name of a new cart to create.
Enter the name without the .p8 extension, as the editor will add .anim.p8 automatically.
WARNING: The editor can only save 0x4300 bytes of animation data to a cart (about 17K). If your animations grow beyond this limit, they will not save correctly and may not reload either.
You can keep tabs on this by running Pico-8 in console mode. The number of bytes written is reported in the console when you save, so you can see when it gets near the 17K limit (for reference, the demo animation is about 3.8K).
Taking frequent backups of your animation file is strongly advised.
Sprite (and tile map) animations are the building blocks of all animated sequences.
Create a sprite animation by clicking the hamburger icon and selecting "NEW SPRITE ANIM".
To edit the animation, make sure the "Properties" section is expanded.
This UI allows you to define a sequence of frames, each of which displays a sprite.
The frames of the animation are displayed horizontally.
Click on a frame to select it.
If the animation has more than 5 frames, click the rightmost frame to scroll right and the leftmost to scroll left.
The "+" and "-" buttons add and delete frames respectively. Adding always creates a new frame at the end of the animation. Alternatively you can insert a new frame immediately after the selected frame by clicking "Ins".
The bottom of the editor shows the available sprites.
As in Pico-8 itself, sprites are grouped into 4 pages, with page number "tabs" at the top right.
To set the sprite for a particular frame, first click on the frame, and then click on the sprite in the sprites area.
The sprite for the current frame is displayed with a white rectangle.
You can also flip a frame horizontally or vertically by ticking "Flip X" and "Flip Y" respectively while the frame is selected.
Information and settings
Click the I icon on the "Properties" bar to display the sprite animation information and settings.
The Name allows you to give your animation a name, so you can find it more easily in the animation chooser.
You should try to choose short names in order to save space and so that they display properly in the animation list. (Ideally the editor would enforce this but it doesn't have enough spare tokens.)
The name is also used to fetch animations when rendering them in your own carts, so it is a good idea to give each animation a unique one.
The Type allows you to choose between a sprite or tile map based animation. (Tile map animations are described in the next section.)
FPS is the frames-per-second speed of the animation.
The value is set using a "number editor" box. Click and drag left/right to decrease/increase the value. Click and drag with the right mouse button to decrease/increase 10x faster.
Size is the horizontal (left box) and vertical (right box) size of each frame in sprites (or tile map tiles, if using a tile map animation).
The Origin defines the origin point of the animation. If the animation is rendered at coordinates X,Y then the origin is the part of the animation that will align with that position on screen. It is also the part of the animation that stays in the same place if you scale it larger or smaller. It's stored as two values ranging from 0 to 1, representing the fraction of the animation's width and height. So (0,0) sets the top left corner as the origin. (1,1) sets the bottom right corner. (0.5,0.5) sets the center.
Hover the mouse over the animation preview area to see the origin point (displayed as a gray cross)
Tile map animations
Tile map animations are special sub class of sprite animations, where the animation frames are defined as sections of the tile map. They are useful for creating larger "sprite" animations, or to define backgrounds for animated scenes.
To create a tile map animation, first create a sprite animation (as described above), click the I to bring up the information/settings and click "Tiles".
Typically you will want to set "Size" here as well (to the width and height of the animation in tiles).
Click the person icon to edit the tile map frames.
The UI is similar to defining sprite frames UI. The main difference is that the tile map is displayed instead of the sprite pages. Use the middle mouse button to drag the tile map around, so that you can select the region that corresponds to your animation frame.
(The UI is unfortunately a bit cumbersome and would have benefited from a mouse-wheel zoom. But it's usable.)
This is the main feature of the animation system: the ability to create animations defined by key frames on a timeline.
Timeline animations are built from other animations, which are often sprite animations but can be other timeline animations as well. In this section we will refer to the other animations as "child animations".
The key frames specify which animations to play at which positions, plus other attributes like scale and flip flags. The animation system interpolates between these values based to create the animation.
Create a timeline animation by clicking the hamburger icon and selecting "NEW TIMELINE ANIM".
The timeline animation UI has two main areas.
Timelines and key frames
The left area contains the timelines and key frames.
The blue top line is for triggering events, like sound effects. This is covered later on.
The gray lines are timelines. Each one displays a single "child" animation. You can include more child animations by creating more timelines, using the buttons at the bottom.
The + and - buttons add and delete timelines respectively.
Use the up and down arrows to re-order the timelines. This controls the order that the child animations are drawn on screen. Timelines are drawn from top to bottom, so the topmost timeline's animation will appear behind the others, and the bottom timeline's animation will appear in front.
The purple dots on the timeline are key frames.
These can be added and deleted with the key frame buttons:
To insert a key frame, first click on the timeline at the position corresponding to the desired time. Then click +.
Note: If key frames are close together it may be difficult or impossible to click on the timeline between them without selecting one of the existing ones. The work around is to click + to create the new key frame anyway, then move it to the desired time.
To delete a key frame, click on it to select it, then click -.
Key frame properties
The right hand side displays the properties of the selected key frame.
Use the number box at the top to set the key frame time on the timeline (drag left/right with the mouse).
(I would have preferred to implement this as dragging the key frame along the timeline, but you know... tokens.)
The key frame properties are grouped into two tabs, which are accesed by clicking the icons to the right of the number box.
The first tab () has the following properties:
Anm selects which child animation to play. Click on the animation name to select it from the list. The child animation will play from this key frame onward. If "None" is selected, the key frame will not change the child animation.
Loop indicates whether the child animation will loop. If not it will stop once it has played to the end (or start if playing backwards).
T and Spd set the time and speed of the child animation. You can use these to start the child animation half way through, or play it in reverse, or double speed etc.
T and Spd are optional properties. This means you can choose not to specify them on a particular key frame, which is useful if you want to add a key frame to change a different property (say the on-screen position). Optional properties are controlled by a tick box on the right hand side which must be ticked in order to enter a value.
For T and Spd there is only one tick box, as you must either set them both, or none at all.
Visible indicates whether the child animation is visible from this key frame onward.
Click the icon to display the second tab.
It has the following properties:
Pos sets the position of the child animation as a X and Y coordinates, relative to the center of the current time line animation. If you render the animation in the center of the screen (like the editor does by default), then 0,0 will position the child animation there.
Pos is an optional property.
It is also an interpolated property. As the animation plays the position will be linearly interpolated between the values supplied on the key frames, so that the child animation moves smoothly from one position to the next.
Sca sets the horizontal and vertical scale factor of the child animation. A value of 1 means no scaling.
Sca is an optional interpolated property.
Flp flips the child animation horizontally and/or vertically from the current key frame onward.
Note: The Visible property is also available on this tab page. It is the same property as on the other page.
Information and settings
As with sprite animations you can click the I icon to display the information and settings.
Refer to the sprite animation section regarding the Name property.
The Duration allows you to specify the animation duration in seconds.
A storyboard animation allows you to play a set of animations one after the other. It is useful for stitching together smaller scenes, like the scenes that make up the demo animation. The editor ensures that each animation starts immediately after the previous one finishes, and adjusts it appropriately in response to duration changes.
To create a storyboard animation, click the hamburger icon and select "NEW STORYBOARD ICON".
The storyboard animation UI is essentially a cut down version of the timeline animation UI.There is no events timeline and only one animation timeline, and key frames are restricted to a subset of properties.
Create the storyboard by adding key frames to the single timeline and setting the "Anm" property to the animation that should play.
Unlike timeline animations, you cannot set the key frame time directly. Instead there are two new key frame buttons that allow you to control their order.
Click the left button to move the key frame to towards the start of the sequence. The right button moves it towards the end.
Timeline animations can also trigger events. These can be used to play sound effects and music, or display text on the screen. You can also create your own event types and handle them in your own carts.
Events are created by inserting key frames into the blue top-most timeline.
The Typ property specifies the event type.
The remaining properties are data to supply to the event handler. If an event handler doesn't use a particular property, you can choose to omit it by leaving its right-hand tick-box unticked (which saves a byte or two in the animation data).
Click on the value to select the event type.
The editor displays the built-in event types that it understands. Or you can click "Custom" to create your own event type. Custom event types are ignored by the editor, but you can implement event handlers in your own carts (this is described later on).
You should keep your custom event names short, as the name string is stored in each event.
The built-in events are as follows:
SFX plays a sound effect.
n=The sound effect number.
MUS starts/stops music.
n=The starting pattern. Omitting it (unticking the right tick-box) indicates that the music should stop.
TXT displays text on the screen.
txt=The text to display
pos=The screen coordinates
n=The number of frames the text will remain on screen
RELTXT displays text on screen relative to the current animation.
This is exactly the same as TXT except that "pos" is relative to the center of the current animation.
CLR clears all text from the screen.
Playing animations in your own carts
Loading and playback code
In order to load and playback animations from your own carts, you will need the loading and playback code.
All this code is in tab 1 of the "Mot's Animation System" cart, and needs to be copied into your cart. Be aware that it will cost you 1836 tokens.
Loading from an external cart
Loading animations from an external cart means that your cart will not be self-contained, and may prevent it from working when uploaded onto the Lexaloffle BBS. However it's relatively easy to setup, and makes for a streamlined workflow, where you save your changes in the editor and simply rerun your cart to load them.
You might want to use this method while developing your cart, and then switch to the embedded Lua string method (described later) once you're ready to release it.
To load from an external cart:
-- load into gfx ram, then decode reload(0x0,0x0,0x4300,"masintro.anim.p8") local stream=readmemstream(0x0) anims=loadanims(stream) -- restore gfx ram reload(0,0,0x4300,gfxcart) -- extract animation to play anim=anims["intro"]
This copies the animation data into memory, and deserializes it into a Lua table.
The process overwrites the sprites and possible tile maps, sfx and music, so the "reload" is necessary to copy them back in from the cartridge ROM.
Individual animations can then be fetched by name.
Rendering an animation
To render an animation, call the "draw" method:
Where t is the animation time in seconds.
By default the animation will not loop, but you can use the "duration" method to achieve this if necessary.
The full list of parameters for "draw" is:
t=The animation time
x,y=The position on screen (defaults to 64,64)
xscale,yscale=The horizontal and vertical scale factors (defaults to 1,1)
flipx,flipy=Whether to flip horizontally or vertically (defaults to false,false)
dt=The delta time from the last frame (defaults to 1/30 or 1/60 depending on whether _update or _update60 is defined)
The delta time is used to trigger events, and tells the animation system how far the animation has advanced since the previous frame. The animation system will trigger all events on the timeline between then and the specified time.
If an animation contains "txt" or "reltxt" events, this text is not rendered immediately by the "draw" method, but queued up to be rendered later. This this allows you to render one or more animations then draw the text last so that it appears in front.
After drawing your animations, render the text by calling the "framedone" method of the "anim_events" global variable:
Handling animation events
When an animation event triggers, the animation system looks for a function on the "anim_events" global variable with the same name as the event to call.
The system sets up a default "anim_events" table with handlers for the built-in events ("sfx","mus","txt","reltxt","clr"), so these events will work automatically.
You can handle your own events by adding functions to the anim_events table.
The parameters are:
ev=The event key frame.
This is a table variable with properties:
Which correspond to the values configured in the animation editor. Property values (except t) can be nil if no value was entered.
x,y=The screen position of the animation that triggered the event.
Note: To save tokens the event is called as a function, not a method. I.e. there is no "self" parameter.
After frame rendering
You can also create event types that render content after the animations have been rendered (like the "txt" and "reltxt" events), by calling anim_events.doafterframe and passing it a function to run.
The function will be converted into a coroutine, so you can use yield() for multi-frame drawing.
For example, here's an event that causes the screen to flash 3 times. The screen will flash white by default, or you can specify a colour by setting "n":
anim_events.flash=function(ev,x,y) anim_events.doafterframe(function() -- three flashes for i=1,3 do -- one frame of white cls(ev.n or 7) yield() -- two normal frames yield() yield() end end) end
Embedding animations as Lua strings
Instead of loading animation data from an external cart, you can embed it directly into your Lua source as hexidecimal strings, to create a single self-contained cart.
For example, here's the demo animation embedded into a cart as a Lua string:
You will need enough free space to fit the strings in without exceeding the compressed size limit however.
To generate the Lua strings you must run Pico-8 in console mode.
Load your animation in the editor, then click the hamburger icon and select "EXPORT ANIMS".
The editor will write a table of hexidecimal strings to the console window. This looks like (on Windows anyway):
You will need to copy it from the console window and remove the "INFO: " line prefixes. You can optionally remove any blank strings at the end of the table.
Then add it to your code, assigning it to a variable. For example:
You can now use the following code to load the animations:
-- load animation from animdata string local stream=readstrstream(animdata) anims=loadanims(stream) -- extract animation to play anim=anims["intro"]
@leissler you create a "Timeline animation", with a timeline for each piece. Then you create keyframes on the timeline to specify what each piece looks like ("anm" property) and where to position them ("pos" property).
Regarding rotation: the editor would need to load/save the value plus make it editable, which I think might fit into the 80 tokens I have left. But yeah, it wouldn't be WYSIWYG.
80 tokens are really not much, I agree.
So I guess before integrating new features you'd have to optimize the whole project to squeeze out enough tokens.
Rotation and scaling would truly make this the picoSpine, though. Very tempting idea, but of course I do not know how much time and dedication you can give this project. Most PICO devs have fulltime jobs and do this stuff in their spare time.
[Please log in to post a comment]