Unreal Matinee User Guide

Document Summary: Guide to using the Unreal Matinee keyframing and cinematic system.

Created by James Golding; updated by Mike Fricker. Maintained by Richard Nalezynski.

Introduction

Matinee is a tool for keyframing the properties of Actors in your scene over time, including their position. It can also be used to author cinematic sequences in your level.

This document explains how Matinee integrates with the Kismet gamplay scripting system, how to create a new Matinee sequence, and an explanation of some of the different Track types.

Using Matinee

Creating A Matinee Action

Matinee is integrated closely with Kismet. It appears as a type of Action within Kismet, and playback is started by connecting one of its inputs to some kind of event in the level. You may want to look at the UnrealKismetUserGuide^? if you are not already familiar with Kismet.

To create a new Matinee sequence, open Kismet and right-click on the background to bring up the `New Object' menu. Under `Actions' you will find `Matinee'. Alternately, there might be an option under that menu that says "New Matineee" which you could also choose or you can also just hold down the M key in Kismet and click where you want the Action. A new Matinee Action should appear, along with an orange `Matinee Data' variable.

The `Matinee Data' is the actual keyframe data for the sequence. You must have a `Matinee Data' object connected to your Matinee Action for it to work. The different inputs on the left allow your Kismet script to control the playback of the Matinee sequence, in a manner similar to a DVD player. The Completed and Aborted outputs on the right are fired when the sequence finishes - `Completed' is fired when the sequence reaches the end and finishes, and `Aborted' is fired if the sequence is playing backwards and reaches the start and finishes. Activating the Stop input does not fire Completed or Aborted. The Object Variables connected to the Matinee Action are the Actors that are going to be modified by the sequence.

There are a few options you can set for the Matinee Action in Kismet:

Movers

Commonly you will want to place actors in your level that are moved around by a Matinee sequence. The easiest way to do this is to add a `Mover' actor to the level. You add these in a very similar way to adding StaticMesh Actors - select a static mesh in the Browser, right click in the level and choose `Add Mover' from the `Add Actor' menu.

Note that it is quite easy for other types of dynamic object to use movement information from a Matinee sequence. For example, if you want to keyframe the movement of a particle Emitter Actor, simply switch its Physics mode from PHYS_None to PHYS_Interpolating.

Opening Matinee

To open the Matinee tool itself, you simply double-click on the Matinee action in Kismet, or right click on it and choose the `Open Matinee' option. It is recommended that you set at least one of your viewports to `realtime' mode when using Matinee, so it will be updated as you playback or scrub through your sequence.

When working within Matinee, Actors in the level will be moved around and have their properties changed as part of previewing the sequence. However, when you exit Matinee, all level state will be restored to the way it was when you entered Matinee. For this reason, you should avoid trying to modify the level or create new Actors while in Matinee, and you will not be able to save the level while Matinee is open. If you try to save your map with Matinee open you will be prompted to close it first.

Matinee Overview

Matinee Layout

Here is a screenshot from the Matinee tool itself:

Menu Bar

File

Export and Import menu commands

• See the following section about exporting and importing Matinee data.

Edit

Undo

Redo

Insert Space At Current

Stretch Section

Delete Section

Select Keys In Section

Duplicate Selected Keys

Save As Path-Building Positions

Jump To Path-Building Positions

Bind Editor Hotkeys Opens the Hotkeys Editor^?.

Reduce Keys

View

Hide 3D Tracks

Zoom To Scrub Position

View Fit Loop

View Vit Sequence

View Fit Loop Sequence

Toggle Curve Editor

Window

Properties Shows the Properties Pane.

Tool Bar

What follows is a description of each of the toolbar buttons, from left to right as they appear on the toolbar.

Curve Editor

See the Curve Editor User Guide page for more details.

Controls

Mouse Controls

Keyboard Controls

Hot Keys

Working with Groups and Tracks

Matinee is structured around the idea of a set of Groups, each containing a number of different Tracks. A Group is associated with a particular Actor in the level

Creating A New Group

To create a new Group in your Matinee sequence, first select the Actor in the level that you wish to modify. Then right-click in the gray bar down the left of Matinee and select `Add New Group' (we will talk about Director Groups later).

You will be prompted for a name for the new Group - it should be unique within that Matinee sequence, and should not contain spaces. When you choose OK, you should then see a new Group header. If you now look at your Matinee Action in Kismet, you can see it has created a new variable connector with the name of your Group, and a new Object variable containing a reference to the Actor you wanted that Group to work on. It is possible to connect multiple Actors to the same Group connector, which is very useful if you want to control the brightness of a number of lights in the same way over time for example.

The little colored bar in the Group header is the editor `Group color'. This is used for various things in Matinee to help you identify which objects in the scene are controlled by which Group in Matinee. It can be changed by selecting the Group and adjusting the GroupColor properties at the bottom of the window. Right clicking on the Group title allows you to Rename or Delete the entire Group. Once you have a Group selected, pressing the Up and Down arrow keys allows you to move it around in the list, which can be useful for keeping similar Groups together.

Note that whenever you select a Group (or Track in a Group) the Actor in the level will be selected for you, and vice versa.

Creating A New Track

A Group on its own does nothing to the Actor it is working on. To actually modify it in some way, we must add a Track to that Group. Right-click on the Group header and it will bring up the New Track menu. This lists all the different classes of Matinee Track that can be added. Select the class you want and it will appear within that Group. Depending on the Track class, you may be prompted for more information before it is added.

Some Track classes (such as the Movement Track) only allow you to have one per Group, whereas others allow you to have multiple in the same Group (such as Float Property Tracks).

If you want to hide all the Tracks in a Group you can press the arrow on the Group header to `fold' it up. You can change the order of Tracks within a Group in the same way as you move Groups - just select it and use the Up and Down arrow keys.

The affect of tracks can be toggled on and off by using the checkmark box next to the name of the track. For example, in the following image, the movement track is disabled and the effects of the track will not be seen when the matinee sequence is run.

Keyframes

The selection and manipulation controls for Matinee are similar to tools in other parts of UnrealEngine 3.

Clicking on a keyframe will move the playback position to that keyframe and put Matinee into `record' mode. Modifying the property of the Actor controlled by that track will then modify the keyframe value. When editing a keyframe, a little red circle will appear in the Matinee info box:

Scrubbing to a different position or beginning playback will take you out of `record' mode and changes to Actors in the scene will not be remembered.

Adjusting Sequence Length

Changing the length of your sequence is very straightforward - simply grab the red handle that marks the end of your sequence (number 22 in diagram) and drag it to the new time you with the sequence to end. It is completely safe to have keyframes outside the range of the sequence.

You can also add time at a particular point in the sequence by moving the playback position to the point where you want to insert the time and choosing `Insert Space At Current' from the `Edit' menu.

The Loop Section

The green area highlighted in Matinee is the `Loop Section'. This is used for several utilities within Matinee, and can be adjusted by dragging the green handles on the scrub bar that mark the beginning and end of the section.

If you press the `Loop preview playback' button (number 3 in diagram), the playback position will jump to the beginning of the loop section, play through it and then jump back to the start again. This allows you to view a small section of the sequence repeatedly to ensure its doing exactly what you want.

You can also `stretch' the current loop section to a new length. To do this, set the loop section over the area you wish to stretch and choose `Stretch Section' from the `Edit' menu. A text-entry dialog will show you the current length of the section, and allow you to enter the new length you desire. Keyframes will be re-spaced over the new length of the section. You can also delete the loop section altogether by selecting `Delete Section' from the Edit menu.

Track Reference

We will now have a look at some of the different Track classes you can use in Matinee.

Movement Track

One of the most important Track classes is the Movement Track. This is used to move an Actor around in the scene over time. Creating a path for an Actor to follow is simply a matter of selecting the Movement track you want to modify and doing the following:

• Scrub to the time when you want to add the new keyframe.
• Press the Enter key or the `Add Key' button to create a new keyframe at that time.
• Move the Actor to the desired position for that frame.

Then repeat this for each keyframe. It is a very good idea to create an initial keyframe for the Actor at its initial position at level load and then not move that keyframe. Otherwise you may see a `pop' when playback begins as the Actor moves to the position proscribed by the animation data.

You will see the path of the Actor in the 3D viewport. Paths are drawn in yellow when the Group is selected, and the Group editor color the rest of time. You can click on the large keys in the 3D viewport to select a key and allow you to edit it in the same way as you would select them in the main Matinee window. The smaller ticks indicate are at 0.1 second intervals, and so give you an idea of the speed of the object.

When a keyframe is selected you will see white handles in the level viewports which allow you to control the velocity at that key and reshape the curve. By default the interpolation mode between keyframes is a curve, but you change the interpolation mode by right-clicking on a key in the main Matinee and using the `Interp Mode' menu. The color of the keyframe triangle in the Matinee window indicates the current interpolation mode its using.

You can also use the `Send To Curve Editor' button (see number 16 in diagram) to use the CurveEditor to get fine control over the translation and rotation of the Actor over time. Use the bShowRotationOnCurveEd and bShowTranslationOnCurveEd options in the Movement track to control whether you are viewing the rotation and/or translation curves.

Movement Reference Frames

There are two reference frames in which you can keyframe your object - `World' and `Relative To Initial'.

`World' is the simplest - it just stores each keyframe as a position relative to the level. When you play the sequence, the object will jump to exactly where in the level you placed the keyframes. This guarantees where your object will be, but can be annoying when you want to move parts of the level around, or re-use your animation on other objects (more on re-using Matinee Data later on).

`Relative To Initial' will initialize the interpolation to start the Actor it is modifying in its current pose. So if the Actor place somewhere else in the level, the movement will be moved as well, and will execute relative to the initial position of the Actor. Also, if a `Relative To Initial' movement track of an object moves it along its local X axis, rotating the Actor would cause it to move in the rotated direction. This makes it very useful for applying one animation to lots of different Actors in your level. Doing so with using the `World' reference frame would cause all the Actors to jump to the same location when the sequence started.

The diagram show a `Relative To Initial' motion applied to two object with different locations and orientations.

To choose which reference frame a Movement track is working in, right click on the Title header on the left and choose the desired frame from the menu.

Rotation Interpolation

Matinee uses two different rotation interpolation schemes to rotate Actors between keyframes - `Euler' and `Quaternion'.

`Euler' is the default and works by interpolating the Yaw, Pitch and Roll of the Actor between the values at keyframes. This allows you to edit the 3 curves for orientation over time in the Curve Editor and control ease-in/ease-out between keyframes. It also supports winding - that is, if you rotate an object multiple times around, the keyframe will store the number of complete revolutions instead of throwing it away. This makes it easy to keyframe something like a screw going into a wall, and also gives you complete control over which direction an Actor takes when moving between two orientations.

`Quaternion' interpolation does not support winding, and is essentially linear between keyframes with no support for ease in/out. However, it is more robust and will always find the `shortest' route between two different orientations.

You can control which method is being used by toggling the bUseQuatInterpolation option (see below).

Rotation Modes

Sometimes you do not want the orientation of an object or camera to be keyframed explicitly. There are 2 different Rotation modes in Matinee at the moment:

`Keyframed' is the default, where the orientation of the Actor is determined by keyframes.

`Look At Group' specifies that you want to Actor to always point at the Actor controlled by another Group. This is useful when using a camera, as you can have it always look at a particular target wherever it moves. To use, type into the LookAtGroupName field the name of the Group in you wish the Actor to point at, and set the RotMode setting to IMR_LookAtGroup.

Movers Relative To Other Groups

It is possible to have a movement track keyframe lookup its transformation info from another group in the same Matinee sequence. This means that a keyframe can point to a moving object and have the movement track interpolate to that position. An example usage case of this would be animating a projectile that always hits a character moving in a non-predictable fashion.

To setup a keyframe to lookup its position from another group, right click on the keyframe and choose "Select Transform Lookup Group..."

This will show a dialog that lets you choose a group to lookup transform information from.

After selecting a group, the keyframe will have the lookup group's name displayed above it. The image below displays 4 key frames that are using the group's Box1 and Box2 to lookup their positioning info.

To clear a lookup group for a keyframe, right click on the keyframe and choose "Clear Transform Lookup Group".

MatineeLookupTest.ut3 is an example map that uses this feature and can be found in the DemoContent/TestMaps folder.

Movers Relative To Movers

In UnrealEngine 3 it is possible to keyframe one object to move relative to another. This may be useful when, for example, you want to keyframe the opening of a door on a moving train carriage.

To do this, simply set the Base of the Actor you are keyframing to the Actor you wish it to move relative to before you begin keyframing.

Movement Track Options

Here is an overview of all of the Movement Track options.

Path Building

Quite often the initial position for Actors like doors is in the `shut' pose. When building the path network for the AI system, it will not be able to find a path through the doorway because the Mover is in the way. To get around this problem, you can set a specific point in your Matinee sequence to be used when building paths. Simply scrub to the point in the sequence you want the Actors to be in when building paths and choose `Save As Path-Building Positions' from the `Edit' menu. A small blue check will appear on the scrub bar to show the current path-building playback position:

For a Matinee Action to move its Actors when path building takes place, you will also need to check the `bInterpForPathBuilding' flag on the Action itself. Note that you cannot have more than one Matinee Action with bInterpForPathBuilding true acting on a particular Actor, as it is ambiguous which position is desired.

Float Property Track

The Float Property Track allows you to modify the value of a floating-point property of an Actor over time, such as Brightness for a light, or DrawScale for a StaticMesh Actor. When you create the Track it will bring up a combo box showing all modifiable properties of that Group's Actor. Select the one you want and then add/modify keyframes in the same way as you would for a Movement Track. You can also use the CurveEditor to adjust the value of the parameter over time.

Vector Property Track

The Vector Property Track works in the same way as the Float Property Track above, but allows you to control a vector property of an Actor - for example DrawScale3D.

Color Property Track

The Color Property Track works in the same way as the Float Property Track and the Vector Property Track from above, but allows you to control a color property of an Actor - for example LightColor.

Event Track

The Event track give Matinee a mechanism for firing events back into Kismet at particular points in the sequence. When you place a keyframe on an Event Track, you will be asked for an Event name. Each discrete Event Name will create a new Output connector on the Matinee Action. When the sequence reaches the Event key, any Kismet Sequence Objects connected to that output will be activated. If you have multiple keys with the same name, one output connector will be created, but it will be activated when each of the keys are passed.

Here is an Event Track with one key called `SpawnBeasts'.

And this is the Matinee Action in Kismet, showing the new output connector, which you can connect to a set of scripted events.

The blue buttons on the Event Track header allow you to control if the output should be fired when the sequence is playing forwards, backwards, or both. If the right hand button is blue, events on that track will fire as they are passed when the sequence is playing forwards. If the left hand button is blue, events are fired when the sequence is played backwards.

It does not matter what Group an Event Track is in, and there does not have to be an Actor attached to its Group.

If you right-click on an Event Key you can rename it. Doing so will rename any other Keys with the same name, and the output connector on the Matinee Action.

Note that event tracks have a bFireEventsWhenJumpingForward property. This property, when set to TRUE, allows all of the events in the track to be fired even if the Matinee is skipped.

Anim Control Track

This track type allows you to easily assign and preview animation on an Actor in the scene. By default, it only works with SkeletalMeshActors, but support can be quite easily added to any Actor class by a programmer.

The first thing to do when using an Anim Control track is to add the AnimSets that you wish to use to the GroupAnimSets array in the group properties. Once you have done this, scrub to the point where you want to start an animation playing, select the track and a new key. You will be shown a combo box containing all the names of AnimSequences in the AnimSets you chose. Simple select the animation you want to play and press OK, and you should see the animation appear as a blue block on the track. You can then move the animation around in the same way you would modify any other key type. Scrubbing will also let you preview the animation applied to the Actor in the editor, which makes setting up complex camera moves and close-ups much easier.

You can also tell an animation to loop by selecting it, right clicking on it and choosing 'Set Looping' or 'Set Non-Looping'. When an animation is looping, it will continue until the end of the Matinee sequence, or until another animation is played on the track. A looping animation will show each repeat in dark blue with a black tick, as you can see with the Fire_Auto_01 animation in the screenshot below:

You can also modify the start and end offset for an animation by right clicking on it and selecting the option from the menu. Another useful feature when working with an AnimControl Track is the 'Razor' tool. This allows you to cut one animation block into 2 pieces at a particular location. Simply select the AnimControl track, scrub to the desired location and press the 'R' key.

Animations can also be cropped/resized using the end markers that appear when the animation is selected. If these markers are dragged normally they will modify the start and end offsets of the animation (cropping the animation). If they are dragged while holding control down, they will modify the playrate of the animation (stretching the animation). If they are held while holding ALT down, they will keep the animation the same time length but modify the start/end offsets and then auto adjust the playrate to keep the animation the same length.

Note that Notifies in the animation will only get executed when the Matinee sequence is being played forwards.

ParticleSystem Toggle Track

The Toggle track gives Matinee a mechanism for toggling Emitter actors on a off at particular points in the sequence. When you place a keyframe on a Toggle Track, you will be asked whether you wish to toggle the actor on or off, as seen in the screenshot below:

The track display will show a green bar when an emitter is toggled on to make it easy to identify the state of the actor. This can be seen below for a Toggle track that turns the emitter on at ~1.0 seconds and off at ~2.0 seconds.

The Director Group

The Director Group is a special type of group that does not work on an arbitrary Actor in the scene like a normal Actor, but implicitly works with the `Player'. It is used when you want your sequence to be a cinematic, and you want to take control of the players view.

You can add a Director Group to your Matinee sequence in the same way as a regular Group, but choose `Add New Director Group' instead. The Director Group header is a different color from a regular Group header to make it easy to find.

There are several Track types that can only be added to a Director Group.

Director Track

The Director Track allows you to attach the players view to different Actors as the sequence proceeds. When you add a new keyframe to the Director track, a combo box will allow you to choose which Group to assign the view to at that point. Colored bars on the Director track allow you to see which Group the camera is viewing through at each point in the sequence - the color corresponds to the editor Group color of each group. If you want to return the camera to the player, simply add a cut back to the Director Group itself. Think if the Director Group as a special group relating to the 'player'. The view will automatically return to the player at the end of the sequence otherwise.

Locking The View To A Group

In Matinee, particularly when creating cinematics, it is desirable to lock the editor view to one of the Actors you are controlling in the scene. When you press the little button on the Group title bar (number 14 in diagram earlier), it locks any perspective viewports to be at the position of the Actor controlled by that group. As you scrub through the sequence, the camera will move with that object. Also, when you move the editor camera, it will move the Actor around to follow it. This can be useful when adjusting a keyframe for an object to look in a particular direction.

When you lock the camera to the Director Group, it will view through the currently `active' camera. This allows you preview what the scene will actually look like in-game. Whenever you open a Matinee sequence which contains a Director group, it will automatically turn on `realtime' mode on any perspective viewports, and lock the camera to the Director Group.

Camera Actors

When making a cinematic sequence, it can be very helpful to use Camera Actors placed in the level. Although you can view through any Actor you have a Group for, CameraActors give you additional properties to control using a Float Property Track such as the camera FOV and aspect ratio, and allow you to graphically see the camera view frustum in the editor.

You can add a Camera Actor to the level by opening the Actor browser, selecting CameraActor from the Actor class hierarchy, right-clicking in the level and choosing `Add CameraActor Here'.

Here is a CameraActor in a level:

The camera mesh and view frustum will only appear in the Editor, not in the game. As you scrub around in Matinee, the active Camera frustum will highlight yellow. Each camera frustum is otherwise drawn using the Group editor color, making it easy to tell which Group is controlling which camera.

When viewing through a CameraActor with `bConstrainAspectRatio' set to true, black bars will be added to the viewport to enforce the screen shape. In the editor, these will only be added when the view is currently locked to a CameraActor.

Fade Track

To control fading of the scene to a particular color, you can use a Fade Track. This Track works similarly to the Float Property Track, but you must use the CurveEditor to control the amount of fading over time. When the Fade amount is 0.0, there is no fading, and when its 1.0 the scene is completely faded out.

Slomo Track

One special effect you can apply to a cinematic is to slow down the game speed. This track again works similarly to the Float Property track, and you use the CurveEditor to modify the slow-motion over time. A Slomo factor of 1.0 will use the default game speed, a lower number will reduce game speed and a higher number will speed up the game.

Slomo affects all game actions, physics, particles etc. as well the speed the sequence itself proceeds.

MorphTarget Weight

SkelControl Scale

Sharing Matinee Data

Because all the data for a Matinee sequence is stored in the Matinee Data variable, and it does not contain any direct references to specific Actors in the level, you can share it between multiple Matinee Actions. This can be useful if you are animating something like a door opening, which you will want to re-use in multiple places in the same level on different Actors. Sharing Matinee Data avoids duplicating the data (thus reducing memory overhead) and makes it easy to modify the movement of all the doors in the level. The Matinee Actions will behave completely independently - opening one door will not affect any of the others. If you do wish to duplicate a Matinee Data variable, you can use Ctrl-W in Kismet as with any other Object.

Below is an example of sharing one set of Matinee Data between two different Matinee Actions, working on different Actors. When you double-click on the Matinee Action, it will open Matinee editing the shared data, but using the Actors linked to that particular instance.

When you connect a Matinee Data variable to a Matinee Action, all the Object Variable and event output connectors will appear. You also connect MatineeData through Named or External variables (see UnrealKismetUserGuide^? for more info).

When using Movement tracks in data shared between multiple Actions, you will almost certainly want to use the `Relative To Initial' frame.

Matinee Replication

Matinee objects that have bClientSideOnly set to false are automatically replicated from server to client. Whenever the action is activated on the server, the server sends that information to the client and keeps them in sync.

Note that this automatic replication only handles Actors with bStatic or bNoDelete set on them (that is, Actors that must be placed in the level in UnrealEd) and the Object variables connected to the matinee must be set to the desired objects in UnrealEd (not at runtime via another action). Actors for which this is not the case are repsonsible for replicating changes caused by matinee themselves using their own UnrealScript or C++ replication code.

Cinematics

In in your game you may have many in-game cinematic sequences but lighting on the characters using the light environments set up may look a bit basic and it may be difficult to really show off the models nicely. In this case, you can use custom lighting channels (sometimes a separate lighting channel for separate characters to control the amount of lights per character), and custom placed dynamic lights to light the characters during close-up shots.

For these sequences, you can use real dynamic lights because they look a little better and give you more control. You should still use very few lights, and often only one of them for casting shadows.

There is a small performance difference, but since cinematics have no gameplay to further slow down things you should be able to get away with it. You may have to have LD's go into cinematic maps and optimize them a few times to get things running smoothly on consoles. In most cases, all static geometry in cut scenes (except for the ground the characters are standing on, which needs real lighting for shadows) can still be light mapped.

Exporting and Importing Matinee Data

Matinee has ‘Export’ and ‘Import’ menu options that allow you to export the entire Matinee sequence out to a COLLADA file that can be loaded into a 3D animation package. This allows you to use an external program to animate the movement of your actors and cameras as well as other properties such as such as motion blur amount and camera FOV. Many aspects of the scene can be exported, such that you’ll be able to visualize your world geometry while working with an animated sequenced.

When exporting a Matinee sequence, UnrealEd will attempt to export most of your scene geometry along with the animation curve data.

The following data will be exported:

• Cameras bound to the Matinee sequence
• Actors bound to the Matinee sequence
  • Animation Curves for certain tracks
  • Movement tracks
• Float Property tracks
• All Lights in current Level
• All Static Meshes in current Level (including polygons, brush geometry and materials)
• All Emitters in current Level (placement cue only)

Note that terrain actors, source brush models and certain other object types are not currently supported for export.

Exported objects will be named similarly to their names in UnrealEd. After making changes to the data in a 3D model package, you’ll want to export the changes back to a COLLADA file where they can be imported into Matinee. It’s important that the names of the objects in the scene stay the same during this process!

When importing the new COLLADA file back into the editor, Matinee will attempt to import all of the animation curves for actors whose imported name matches an actor bound to the active Matinee sequence. In some cases (such as for cameras), you can also add new objects by creating them in the modeling package and exporting them to COLLADA format.

Notes:

• It appears as though this feature has only been thoroughly tested with 3ds Max and although you can work with the COLLADA file in other packages, there may be problems with the orientation and scale of the curves that you’ll need to work around.

• The default COLLADA importer with recent versions of 3ds Max (FBX importer) doesn’t appear to support the files generated by UnrealEd. We recommend using Feeling Software’s ColladaMAX tools instead. The version of ColladaMAX we tested with is 3.02.