Given a set of animation segments, the main purpose of those machines is to organise them on a single timeline. It describes all the possible sequences and all the possible transitions between them.
Users may interact with the machine by setting its mode. Modes are user-defined names (e.g. walk, run, jump, crouch, ..) that guides the machine when transiting. A machine describes the modes it accepts and the modes it refuses. Each state also describes the modes it accepts, the modes it refuses, and what happens when a new mode is set while the machine is in this state.
States are sequences. A sequence is a combination of actions such as playing an animation or sending an event. Machines carry on playing sequences one after the other on their timelines and rewrite this timeline when its end has been reached or when a new mode is set (transition).
Targets describe what machines control. The effects of their sequences can occur on the full geometry or be restricted to a subpart of it. Targets define what geometry will be affected by the sequences and which ones won't.
Targets can be defined as follows:
QAM file accepts two kinds of comments.
All comments are ignored when building the machine. Their only purpose is to allow the user to add any extra information to the file.
QAM file layout
A QAM file describes targets and machines.
Target definitions are defined after the keyword target and are described here.
Machines are defined as follows:
The name is optional and is used to reference the machine if needed. So typically an QAM file looks like:
They describe the attribute specific to the machine and are defined as follows:
Possible attributes are:
It defines the machine possible modes. The machine can only be in one mode at a time and this mode can only be part of this set. Modes are defined as follows:
They describe the states of the machine. At a particular time, the machine is either in the empty state (inactive) or one of those states (active). State definitions are the main components of an animation machine. A detailed description is given here.
Machines may delegate the control of a subpart of their target to a different machine so that the original target can be animated by overlapping timelines. This process is called delegation and described here. Sub-machines are defined exactly as machines and their definitions go in the body of their parents.
The name characterizes the state in the machine. It is optional and in case it is omitted, a name deduced from its sequence definition will be used (the name of the first animation segment appearing in the sequence definition).
The sequence property describes the sequence that gets played when the machine is in this state. Possible sequence definitions are described here. If no sequence is defined, the state waits until a transition becomes possible.
Transitions describe what happens when the mode changes or when the sequence starts or stops playing.
Modes or list of modes are on the left and the sequence that gets trigger when the transition occurs is on the right (separated by colon). The keyword default is used to represent all the modes which have not been listed in the transition set. If a mode is missing and there is no default transition, it will be regarded as a failure for this state and will be refused by the machine.
There are 3 types of transitions between 2 sequences.
Here is an example that shows how to define each kind of transitions
The first two ones are straightforward and fully described here. If the machine mode is set to walk, the sequence with this transition set will be cut and stan1tostep1 will start to play. The machine will jump to the corresponding state if it exists. If the machine mode is set to run, the behaviour will be similar except that the sequences will be tweened in 0.4 seconds. The last transition uses the special keyword $ that represents the end of the timeline. So $ + ... can be understood as add to the end of the timeline. If the machine mode is set to jump, the machine will wait until the end of the current sequence and then jumps to the stan1tojump1 state.
A transition may explicitly fail too using the keyword fail. Internal modes are refused by default if they are not part of the transition set of the state. The failure set is useful to explicitly refuse external transitions of other machines and thus resolve conflicts between machines.
Transitions may be multiple and weighted for the same mode. In this case, the weight indicates how frequently this transition will be preferred to the other transitions associated with the same mode. For instance, if a transition t1 has a weight of 4 and another one t2 a weight of 2, t1 will be two times more likely to be triggered. If no weight is indicated, it is equal to 1 by default.
A mode is internal if and only if it is part of the mode set of the machine (called external otherwise). An active machine can only be in one and only one mode at a time and this mode must be part of the mode set (i.e. internal)
States can raise user-defined events in order to interact with user code. Events can be inserted at any time in sequence definitions using the keyword event(<name>).
Transitions can be forced in any sequence definitions using the keyword transition(<mode>). If the machine encounters this keyword, it will set its mode to the new value and carry on. The requested mode has to be internal.
Machines sometimes need to give control of a subpart of their target to another machine so that independent animation cycles can take place at the same time. For instance, a machine may control the walking cycle of a character. This character can also draw his gun out and fire. While firing, the character may still walk around. When this happens, the machine needs to delegate the firing cycle to another machine so that firing and walking can occur independently and simultaneously.
Machines may have machines as children. Those sub-machines are inactive by default. They might be activated by using the keyword branch(<machine>, <sequence>) in a sequence definition. If the machine executes this keyword in one of its states,
Note that transition modes that trigger branching are external in general so that they do not interfere with the general cycle of the machine. Sub-machines may then be deactivated by using the keyword merge in a sequence definition. In this case they lose all control over their target which get controlled back by the parents.
Let's illustrate with an example:
At the beginning, machineA cycles the sequence cycleA on the whole target. If the mode twoMachines is set, the machine starts tweening with a time of 0.2 seconds and then activates machineB. It keeps the control over the target partA but delegates the control of all the rest to machineB. The latter cycles the sequence cycleB over this part (while machineA keeps cycling cycleA) until the mode oneMachine is set. At this moment, targets get merged and machineB is deactivated.
States may reuse transitions defined in other states. This mechanism is called inheritance. Possible transitions will first be looked up in the usual transition set. If a possible transition exists, it will be triggered. Otherwise, the transition will be tried against the transition set of the parent set.
In this example, the states idle and attack inherit from the state base. This state defines a set of generic transitions that may be shared by several states in the machine. For instance, if the machine is in the state attack and the mode gets set to hit1, then the machine will jump to the state hitReaction2 because the current state inherits from the base state. Note that transitions may be overridden to reflect the local oddities of a state too:
State machines that organises sequences on a timeline. States are sequences.
User-defined name that allow the user to control the behaviour of a machine. Each machines have a set of modes. A machine can only be in one and only one mode at a time and this mode must be part of this mode set. A mode is said internal to a machine when its part of this set.
Element of the sequence algebra defined here.
Link between a geometry and sequences. Targets define what geometry will be affected by sequences and which one won't. See here.
A machines delegates when it gives control of a subpart of its binding to another machine. See here.
Mode that the machine refuses.
User-defined name that allow the user to react to the behaviour of a machine. See here.
The state the machine starts in by default.
A machine is active when its current state is valid.