Animation States

A Molkit animation is a sequence of states. Each state is a snapshot of your drawing at one moment, held inside its own frame on the canvas. During playback Molkit holds each state, then moves every matched object to its place in the next state. Preview and Export become available once you have two states.

Example: animate an SN2 reaction

The quickest way to learn states is to build one small mechanism: hydroxide attacking bromomethane.

Draw hydroxide (an O with a negative charge and its lone pairs) to the left of bromomethane (CH3Br). Add the two mechanism arrows: one from an oxygen lone pair to the carbon, one from the C-Br bond to the bromine.
Click the Animation Mode button in the tool toolbar, or press Shift+A.
Click + New State and drag a rectangle around both molecules and the arrows. That frame is state 1.
With state 1 active, click Duplicate. A copy appears in a new frame to the right as state 2, and every copied object is already paired with its original.
Edit state 2 into the products: delete the arrows, delete the C-Br bond and draw a bond from O to C, remove the oxygen lone pair that attacked and add a fourth lone pair to bromine, move the bromine away, and move the negative charge from oxygen to bromine. Or, in step 4, click Next Step instead of Duplicate: it makes those bond, lone pair and charge changes from the arrows for you, and you only move the bromine away (see Next Step from arrows).
Look at the chip between the two thumbnails in the state strip. Green means every object is paired one to one. If it is amber or red, see Object Matching.
Click Preview. The arrows draw on state 1, the oxygen lone pair stretches into the new C-O bond, and the C-Br bond contracts into the new lone pair on bromide as it moves away.

The lone pair and bond motions in step 7 come from the lone pairs you added and removed in step 5; Reaction Choreography explains the rules, along with the order in which the arrows draw.

Enter animation mode

Click the Animation Mode button near the right end of the tool toolbar, or press Shift+A. The animation toolbar appears with the state controls and the docked Animation panel opens on the right. Press Esc or click Exit to leave. You can also double-click a state frame’s header while outside animation mode to enter it with that state active. Animation Toolbar describes every control.

Create a state

Click + New State. The cursor becomes a crosshair. Drag on the canvas to draw the state frame; atoms inside the rectangle, bonds whose atoms are both inside, and annotations inside all become the contents of the new state. The crosshair stays armed so you can draw several frames in a row. Press Esc to stop drawing.

States are not separate copies of your document. The objects stay on the canvas, and each state records which objects belong to it by ID. Anything you later draw or move inside a frame joins that state the next time you enter animation mode.

State frames on the canvas

Each state draws as a rounded rectangle with a header showing its name (“State 1”, plus a custom title if you set one). The active state has a solid blue border; inactive states are gray and dashed. Outside animation mode the frames stay visible but dimmed.

Click inside a frame to make that state active.
Drag the header to move the frame together with its contents.
Drag the square handles on the active frame’s corners and edges to resize it.
Click the eye icon in the header to exclude the state from preview and export. The frame grays out and its transitions show no duration. Click again to include it.
Shift+drag the header to clone the state and drag the copy into place.

Duplicate a state

Select a state and click Duplicate. Molkit clones every object in it with fresh IDs, places the copy in a new frame to the right, inserts the new state directly after the source, and pairs each copy with its original, so the transition moves objects instead of fading them. States play in the order they were created, so duplicating is also how you insert a step in the middle: duplicate the state before the gap, then edit the copy.

Next Step from arrows

Next Step works like Duplicate, but carries out the curved arrows of the active state on the copy. Each arrow moves one pair of electrons, and the copy gets the result:

A lone pair to an atom forms a new bond between them; the lone pair is used up.
A lone pair to a bond the atom is part of raises that bond’s order by one.
A bond to one of its own atoms breaks one pair of that bond and gives the atom a new lone pair.
A bond to another atom moves that pair into a new bond from the nearer end of the bond to the atom (a pi bond attacking an H, for example).
A bond to a neighbouring bond shifts a double bond along (one order lower on the first bond, one higher on the second).

Formal charges change to match: the atom that gives electrons away gains a plus, the atom that receives them gains a minus. The copied curved arrows are removed, everything else in the state is copied as is, and the copy’s objects are paired with the originals like a duplicate. Atoms stay exactly where they were, so you only rearrange the layout. The whole step undoes in one Ctrl+Z.

For Next Step to read the arrows, draw every lone pair and charge in the state, and attach both ends of each arrow: the tail to a lone pair or a bond, the head to an atom or a bond. Next Step is strict. If any arrow cannot be read with certainty, nothing is created and a message lists the problem, for example an end that is not attached, a tail on an atom with no lone pair, a head on a bond that is equally near both of its atoms, or a bond that would lose more electron pairs than it has. Single-electron (fishhook) arrows are not supported yet.

A few details:

A lone pair you positioned by hand goes back to automatic placement on atoms whose lone pair count changes, because the old positions no longer fit.
Straight arrows and pointer arrows (a caption pointing at an atom) are not read and stay in the copy.
Next Step is for structure animations. In a LaTeX solution animation it shows a note and changes nothing.
The new frame is placed the same way as with Duplicate. When you use it on a state in the middle of the sequence, the new frame can land on top of the next state’s frame; drag it aside.

Edit, rename and delete

With a state active, edit its contents with the normal drawing and selection tools: move atoms, change bond orders, add or remove annotations. Neighbouring states differ only in what you change, and the engine animates the difference.

To rename a state, double-click its title in the state strip, type a title, and press Enter, or set Name in the Animation panel while the state is selected.

To delete the active state, click Delete in the animation toolbar or press Delete with nothing selected on the canvas. Only the frame and its place in the sequence are removed; the drawn objects stay on the canvas.

What each state stores

Some settings belong to a single state, some to the step between two states, and some to the whole animation:

Scope	Settings
One state	Title, frame position and size, the excluded (eye) toggle, custom pivot atoms, time on screen
One transition	Duration and motion, automatic unless you override them
Whole animation	State order, speed, pivot mode, and the object matches for each pair of states

Every duration is worked out automatically from what happens in each step. You only need to set timing when you want something different; see Animation Timing.