Reaction Choreography

When an animation plays or exports, Molkit compares each pair of adjacent states for chemical changes: lone pairs that become bonds, bonds that break, bond orders that change, atoms that move from one molecule to another, and the curved arrows you drew to explain it. Each change it detects gets its own motion in place of a plain slide and crossfade. Detection is automatic and uses only what you drew, so there is nothing to configure per reaction.

How objects pair up between states is covered on the matching page. How long each step lasts is covered on the timing page.

Mechanism arrows

When arrows appear

Arrows that are new in a state draw in after the molecules arrive in that state, one at a time. Curved mechanism arrows in the first state draw in before anything moves. When the state is done, its mechanism arrows retract over 450 ms at the start of the next transition (never more than half of the transition).

Draw order

Arrows draw in the order of the mechanism:

Arrows that start at a lone pair (the attack).
Arrows that start at a bond (the bond that breaks).
Any other arrows.

Within each group, arrows keep the order you drew them in. Each arrow takes 800 ms, and the next one starts 350 ms after the previous one.

How an arrow draws

A curved arrow draws along its own path from tail to head, and the arrowhead appears at the end of the draw. When it leaves, the line retracts from the tail into the head, so it disappears where the electrons went. This works for U-shaped arrows too: the two legs appear one after the other, not at the same time.

Arrows drawn as a filled outline (straight and reaction arrows) and arrows with a dashed stem are revealed with a sweep instead.

Drawing arrows the animation can read

Anchor both ends. Start the arrow on a lone pair, radical or bond, and end it on an atom or bond; an anchored arrow records which electrons move and where. See mechanism arrows for how snapping works.
Start the attacking arrow on the lone pair itself. An arrow whose start is attached to a lone pair is recognized as the attack and draws first.
Start the bond-breaking arrow on the bond, so that it draws second.
Keep unanchored arrows close to the atoms. An unanchored arrow end is matched to the nearest atom only if it lies within 20 units of it; farther away, the arrow is ignored for electron motion and the electrons follow a generic arc.

Lone pairs and bonds

When a lone pair becomes a bond, the lone pair and the bond are animated as one object. The two dots slide onto the bond axis, the far dot moves to the partner atom while a line grows between them, the dots shrink into the ends of the line, and the line becomes the new bond.

The reverse also happens. When a bond breaks and one of its atoms gains a lone pair, the bond contracts toward that atom, turns into two dots, and the dots move to the lone-pair position.

This applies when the atom at one end of a new bond loses a lone pair, or the atom at one end of a broken bond gains one. It also covers a lone pair that becomes the second line of a double bond, and a double bond whose second line becomes a lone pair, and bonds drawn as partial bonds.

Bond order changes

When a double bond becomes a single bond, the second line folds into the first. When a single bond becomes a double bond, the second line separates out of it. The two versions of the bond never crossfade.

Labels that absorb an atom

When an atom merges into a neighboring label between states (for example CH3 and O in one state become the single label CH3O in the next), the bond from the rest of the molecule slides to the new label instead of fading out and in again, and the label shifts aside to make room for the added text.

The opposite happens when a group label splits. When an OH label in one state becomes an O with an explicit H bonded to it in the next, the oxygen’s lone pairs stay visible and turn to their new places while the rest of the label changes. The H starts in the label’s colour and takes its own element colour as it moves out. An explicit H absorbed back into an OH label does the reverse. This works the same in the preview and in exported files.

Staged transfers

When an end atom such as a hydrogen moves from one molecule to another, Molkit stages the transfer in two phases. The smaller molecule approaches and turns so that the accepting lone pair (chosen from your arrow) faces its partner, the atom moves across, and bonds and charges change as it lands. The molecules then move apart to their positions in the next state.

This applies when the moving atom has only one bond in both states, and its old and new partners are in different molecules in the second state. A transfer within a single molecule uses the normal motion. A staged transfer takes at least 1.4 seconds.

Leaving and arriving molecules

A molecule that exists only in the first state drifts away from the reaction center as it fades out, and a molecule that exists only in the second state drifts in toward it. The drift distance grows with the size of the molecule. A leaving group that is still bonded waits until its bond breaks before it moves, an arriving molecule that will form a bond lands before the bond forms, and two molecules that would cross paths move one after the other.

This applies to whole molecules only. An atom that is bonded to something that stays slides into or out of its neighbor instead (see Unmatched objects).

Reaction patterns

Between each state pair, Molkit also checks for three patterns:

A nucleophilic attack: one atom loses an orbital, another loses a lone pair, and a new bond connects them in the next state. If the orbital atom also loses a bond, that bond’s far atom is treated as the leaving group, and a lone pair gained there is part of the pattern.
An electron transfer: a matched atom’s lone-pair or radical count drops while another atom’s rises. Donors pair with acceptors through a curved mechanism arrow first, then through a forming bond; radicals can also pair by proximity. Lone-pair transfers require an arrow or a forming bond, so stray lone-pair edits are not animated as transfers.
Radical pairing: a forming bond whose ends carry radical electrons gets a short rotation beat before the transition, turning each radical to face its partner before the bond appears.

A pair with any of these patterns uses a fixed 3-second transition. For a nucleophilic attack, the transition runs in overlapping beats:

Approach (roughly the first third): structures move into position while the lone pair and orbital stay fully visible.
Merge (middle stretch): the lone pair and orbital dissolve as the forming bond fades in. A breaking bond fades out during this window, so the bond visibly breaks before its atoms leave.
Solidify (final stretch): the new bond reaches full opacity and the leaving group’s new lone pair appears.

During an electron transfer, electron dots travel from donor to acceptor: a pair of dots for a lone pair, single dots for radicals. They follow your drawn arrow when one exists, otherwise a gentle arc. When a lone pair becomes a bond, the lone-pair animation described above shows the electrons instead of a travelling dot.

Arrows that describe a detected attack, departure or electron transfer draw on during the transition itself, in step with the electrons, and fade near its end.

Choreography has no off switch. Removing the lone pairs, orbitals or arrows that trigger it returns a pair to the plain transition.

Preview and export

The preview window and the exported animation show the same motion: arrow drawing, lone-pair and bond changes, drift, transfers, and the timing of charge and label changes.