Using Splicer

Starting Splicer

Splicer is a plugin for Composer. With Windows binary installs, it can be accessed from the start menu. For source releases, open a command line window and navigate to the trunk folder (the base of the MV3D source tree where the mv3d folder is) and run

python mv3d/tools/composer/composer2.py

For setuptools installations, make sure Python's scripts directory is in your path and just run composer2.

Overview

Splicer is an advanced tool for making parameter driven animated actors. It is able to blend together animations, sound effects, and particle systems (support for the last two coming soon) to produce synchronized actions. The underlying basis for Splicer is the CompositeMaster?, which is based on a state machine. To explain, it has several states which can be transitioned into or out of. For example, a CompositeMaster? for a character may have a walk and an idle state. Upon entering the walk state, they play the walk animation and stop the animation when leaving it. When inside a state, events can trigger actions or transitions to other states.

Characters in Splicer can be controlled or altered by parameters. Adding to the previous character example, a walkSpeed parameter could be added. Listeners on events triggered by this parameter changing in the idle and walk state could switch between idle and walk depending on whether the value was 0 or 1.

Sequences

Sequences represent the various states in the state machine. This tree view shows sequences and the events they listen for. Double clicking on a sequence will force it to become active. If it's a newly created sequence, then using File->Rebuild on the menu is required. Right clicking on a Sequence brings up a context menu which allows for adding events amongst other things.

Events

All Sequences have at least two events. These are enter and exit. They are called when the sequence is activated and deactivated respectively. Most of the time a startAnimation action is placed in the enter Event and a stopAnimation action in the exit. It is possible to add extra arguments to the enter event as they can be used to pass state between Sequences. Events have script code associated with them which dictates what the event does when it is called. The script is standard Python. If you don't know how to write scripts or Python, don't worry, 90% of the required functionality can be added using just the GUI.

Properties

Properties are effective for whatever is selected in the Sequences tree. There isn't a lot here, mostly the name of the selected and the description. The Overlay checkbox for Sequences specifies that the sequence can be active at the same time as other sequences. This is generally useful for additive animation or Sequences that have no animation component at all. Overlay mode is currently not supported.

Parameters

Parameters have two purposes. They can be used to hold state that is accessible from all Sequences, and they can be used to control the CompositeMaster? from outside. This means that the client application can be made to change parameters which trigger events to manipulate the character. Parameters have a name, value, and type. The type denotes whether they are a number, text (string), position, or orientation. Other parameter types may be added in the future.

Status

The status pane shows the current active animations. This can be useful for debugging.

Editor

The editor window can be used to directly enter script code for events. As mentioned earlier, Python is used for the scripting language. In all events, the CompositeMaster? can be accessed by the controller variable. There are many useful commands that can be accessed from the controller:

• controller.activate("sequence name") - Active the Sequence named "sequence name".
• controller.startAnimation("AnimName", loop=True, weight=100, speed=1.0, blendTime=None) - Start an animation named AnimName?. The remaining parameters are optional and they specify whether to loop the animation (versus playing it once), the weight to apply the animation at, and the speed. The final parameter (blendTime) can be used to specify an amount of time in seconds to fade the animation in.
• controller.stopAnimation("AnimName", blendTime=None) - Stop an active animation named AnimName?. Similar to controller.startAnimation, the blendTime parameter can be used to specify an amount of time in seconds to fade the animation out.
• controller.parameters.Run - Access the parameter named "Run". Parameters can be read or set in this way.

Arguments

The Arguments tab is for adding and removing event arguments. Most events can have extra arguments passed to them. To add new arguments, just specify the name in the text box and hit the plus button. To remove them, select one and hit the minus button. Arguments can be accessed by simply typing their name in the Editor window.

Animations

The Animations tab shows all animations available. To refresh this list, use Animation->Add animations from mesh on the menu. Right clicking on an animation brings up a context menu which can insert into the Editor a start or stop command. The third option in the menu will add a new event to the selected Sequence which will be called when the animation finishes.

Callbacks

Animation callbacks are time offsets for an animation that will trigger an event to fire on the active Sequence. This can be useful to ensure perfect timing of other actions such as starting sound effects when a sword swing connects with the target. To edit callbacks, first select an animation. The plus button can be used to add a new callback and the only parameters are name and callback time. Right clicking on a callback brings up a context menu which can be used to add an event handler for that callback to the currently selected Sequence.

Sockets

Sockets are attach points for weapons, particle systems, or accessories. They are defined with a name, a bone in the mesh's skeleton to attach to and a position and orientation which are offset from that bone. To add a socket, hit the plus button. When a socket is selected, a white cube mesh will be attached to the socket to identify the position and rotation of it.