Unreal Director's Suite
The Unreal Director’s Suite (UDS) is a set of tools that are useful for creating in game cut-sequences using Unreal Engine 1. It has been designed to make laying out and implementing detailed cut-sequences as simple as possible.
NOTE: This is an adaptation of the original documentation for the package by Creative Carnage.
How the system works
There are 5 major components of the UDS system. They are: GameInfo’s, Cameras, Sequences, Hud and Custom Player classes. By default the UDS comes complete with two new game types. They are CSSinglePlayer and CSMovie. The UDS does not have support for Multiplayer and Co-op games.
The CSSinglePlayer game type should be used for your typical map. It behaves for all intensive purposes just like the original Unreal SinglePlayer game type. The difference is it forces the player to utilize our special player classes and makes doing a cut-sequence possible.
The CSMovie game type is a child of CSSinglePlayer. It should be used by people who are only interested in creating non-interactive movies. It will automatically find and trigger the CSAction actor (see below) as soon as the map starts.
The second component of the UDS is the camera (CSCAMERA). Right now there is only 1 type of camera in the UDS. It can be placed anywhere in a level and can be triggered through any sequence. Once triggered, the player’s view is switched to the position of the camera.
The third component is the actual sequence. A typical sequence will have 3 parts. The CSAction actor which can act as a trigger to start the sequence, multiple CSShotLists which hold the script for the sequence, and a CSWRAP actor which is called when the sequence is completed.
The CS_Hud is a new hud class that handles the different overlay tricks needed for some of the effects as wells as display the debug information.
Finally, the CSPLAYER and all of the replicated CSHuman (and subclasses) hold all of the necessary game data.
A typical cut-sequence (C/S) works as follows. The player triggers a CSAction (either by touch or by trigger). The CSAction sets up the HUD, performs pre-sequencing (freezing actors, setting the initial camera, etc). Finally, control is transfer to the first CSShotList. This actor contains the script for the sequence. Finally, when the sequence as finished, the CSShotList calls the CSWRAP actor which returns everything to normal.
Adding the UDS to your mod
This is probably the most difficult part of this documentation. If you haven’t yet begun your mod, you will want to use the UDSdemo code as a starting base. This will make your life easier as all of the base UDS code has been written for you.
If however your mod is already under development, the UDS can be added without too much trouble. Most of the UDS is 100% stand-alone code… but the whole system relies on three different classes: CSPlayer, CSSinglePlayer and CSHud. In order to make the UDS work with your mod, you must done one of two things.
Making your mod conform to the UDS
If you mod hasn’t already made changes to the PlayerPawn/UnrealIPlayer classes, the game types or the Hud, the road for you is easy. All you need to do is include the source from the UDSdemo with your current code base. In some rare cases, you will need to go in and fixup any references your code makes to the any of the above classes, or any subclasses of UnrealIPlayer. However this in most cases will not be needed.
Making the UDS conform with your mod
If you have already changed the PlayerPawn/UnrealIPlayer classes, the game types or the Hud, you have a much harder job. You will need to implement most of the funcationality in to your own code. None of these changes are difficult but they can be time consuming. Let’s look at the changes you will have to make
Step One: Merge in our CS_Hud code in to your Hud mode. Most of your work here will be implement the functionality of our PostRender function in to yours. After that, you can copy the support functions fairly verbatium.
Step Two: Make sure your game type sets up to call your custom HUD so that the UDS can do the letterbox effects and such.
Step Three: You need to implement the functionality of our CSPlayer in to your custom player class. The quickest way to do this is to simply change your player class to be a subclass of CSPlayer, not UnrealIPlayer.
The CSPlayer Class
Probably the most important piece of the UDS is the new CSPlayer class. Any human control player in the game, must be a sub-class of the CSPlayer (which in itself is a sub-class of UNREALIPLAYER). This new class has all of the necessary variables, functions and states that make the UDS possible.
By creating a map of the game type CSSinglePlayer or CSMovie the LOGON code for that game type will automatically filter the player’s character selection to match one of the included custom classes.
This becomes important as you try and merge the UDS in to your mod. Any reference to HUMAN, MALE, FEMALE, MALEONE, MALETWO, MALETHREE, FEMALEONE, or FEMALETWO will need to be fixed up to reference their CS counterparts (this doesn’t happen anywhere inside the original Unrealscript). Additionally, any changes or references you make the PLAYERPAWN or UNREALIPLAYER should be re-referenced to the CSPlayer.
This includes the addition of any variables, functions or states. The CSPlayer is critical to the entire UDS system. With this in mind, let’s go over it more closely.
There are really 3 different sections to the CSPlayer class. The global variable declarations (they come immediately after the class definition), the PlayerActing state, and the various support functions. In this UDSdemo example mod I’ve created, I’ve also included the additional state LadderClimbing. This state is used specifically when the LADDER actor is touched in the game.
Let’s look at each section starting with the variable declarations.
var bool bCSCameraMode; var CS_Camera CSCamera;
When bCSCameraMode variable is TRUE, the UDS is active and performing a cut-seuqence. This variable is mostly used in the SHOWMENU() function to determine of a C/S should abort, or if the command should be ignored. The CSCamera is the current camera that the C/S is setting the view point from.
var int oldhudMode; var bool bIsActing; var bool bCanEsc;
The OldHudMode variable is used to track what the last hud was. This is important as when we switch in to a C/S the hud get’s completed overtaken. The BOOL bIsActing is set to TRUE while the player is in a C/S that has player movement frozen. It’s used to flag the fire and movement code to ignore player input.
var string[240] CSDebug1; var string[240] CSDebug2; var string[240] CSDebug3; var string[240] CSDebug4; var string[240] CSDebug5; var string[240] CSDebug6; var int CSDebugCnt; var string[240] CSLastAction; var bool bCamDebug; var bool bCSInDebug;
All of the about variables relate to the new debug code built in to the UDS. Feel free to figure them out.
var CS_SpikeTape CSMoveTarget;
When use tell the player actor to move (using the CSPlayerMoveTo command) this variable will be set to the destination CS_SpikeTape.
var CS_ShotList CSShotList;
The CSShotList variable holds the currently active CSShotlist in the sequence. It’s used to quickly allow the player to reference back to the active shotlist when a callback is needed (for example, the player touches a CS_SpikeTape).
var float CSAbortSpeed;
CSAbortSpeed is experimental. I’m working on allowing the player to abort a sequence but have all of the triggers and such triggered. So far it really doesn't work but feel free to player with it.
var vector AdjVelocity;
AdjVelocity stores the vector that’s used to control player movement. Unfortunately, the PlayerPawns (and all subclasses) cannot use the intrinsic MOVETO function of Unreal. For the time being, we have to force actual velocities in to the player.
In the future, I will probably just create a dummy player actor that can be control as any other pawn. Boy will that make life easier.
In addition to the difference variables needed, there are several global functions that have been added to the PlayerPawn class (via the CSPlayer). They are:
PlayerCalcView
We overload the PlayerCalcView function for the PlayerPawn to allow for us to reset the current viewpoint to that of our camera. Of course, the location and rotation are both used.
POVGotoLocation
This function will cause the view to switch to a new location. In order to simplify things, we reset the new camera’s rotation and velocity before we make the final switch. We also turn off all tracking, etc.
POVThirdPerson
This function has switches to the behind-the-view mode. This is necessary to remove all the of different weapon models, etc.
POVFirstPerson
This function is called to return the view point to that of the player.
ShowMenu
The ShowMenu function is overloaded. We need to check to see if we are in a C/S before attempting to bring up a menu.
Freeze
This is a function that switches the player in to the state PlayerActing and back again. It gets called by a CS_Action.
ScriptedMove
This function adjusts the velocity of the player. God I wish there was a better way to do this, but so far I haven’t figured it out.. if you do.. please let me know.
ResetScriptedMove
Stops the player from moving.
CSAddDebug
This function is used to add a debug message to the output buffer.
The final set of global functions are useful debugging and creating your C/S. The first is DebugCS. When this EXEC function is called from the console, the UDS will enter a visible debug mode. In this mode, various (and important) information about the C/S will be displayed while it runs. This information is EXTREMELY valuable in determining problems.
The ListCameras EXEC command will give you a listing of all the cameras in the level. You can then use the GotoCamera EXEC function to change your view to that camera. This is usefull for seeing the position of a camera before the sequence starts.
These two functions become even more usefull when you bind the next 2 EXEC functions to keys. CamMove and CamAdj can be used to position the cameras in real time while in the Unreal game engine (not the editor). The locations of the cameras are then displayed on the screen. You can write these new locations/rotations down and enter them by hand in to the editor.
They use the following formats:
CAMMOVE newx, newy, newz CAMADJ newPitch, newRoll, newYaw
Finally, there is the EXEC function ResetView which returns you from a camera.
Rounding off the CSPlayer class, is the new state PlayerActing. While in the state, the player will only move or act when told by the CSShotList. Feel free to disect it.
As I stated, I’ve also included the state LadderClimbing. Feel free to experience with ladders in your map (a sorely missed omission from the original Unreal game and something everyone’s been pestering me about).
The CS_Action Class
One of the 3 major UDS classes is the CS_Action. This is the initial trigger that will start the cut-sequence. It takes several parameters that are used to setup the initial settings. They are:
Retriggerable – When set to true, the C/S can be triggered time and time again. However there is a built in 3 second delay before the trigger will again happen. Retriggerable C/S are good if you are using it in conjunction with a static sequence (say the player moving up/down on an elevator).
bOnlyTriggerable – If this flag is set to true, the CS_Action will ignore the player touching it and force an alternate trigger to be used.
FirstShotList – This is the name TAG of the first CS_ShotList in the sequence. Once the CS_Action is done setting up the sequence, control will be passed to the CS_Shotlist that matches this tag.
LetterBoxed – This flag effects the final display of the sequence. When true, it forces the hud in to a “LetterBoxed” mode. This is a video/film term that is in regards to the 16:9 ratio. Personally, I think all C/S should be done in LetterBoxed mode. This helps the player differentiate between the game and the C/S.
FirstCamera – This should hold the name TAG of the first camera in your C/S. If none is found, the C/S system aborts.
FirstLock – This field is used to lock the camera on to a target. The reason it exists is to avoid a sudden SNAP in to position the camera makes. Though not normally visible, this Snap can show up when it’s done to the first camera.
A special TAG is available in this field. If you enter SELF for the FirstLock, the C/S engine will lock the initial camera on the player. For more information, see the CS_ShotList definition below.
FreezeActor – This flag is used to control other actors in the game. When set to true, the player is locked from doing anything during the C/S. Also any creatures you create of type CSPawn (see below) will also freeze.
The CS_Wrap Class
As you learned above, the CS_Wrap class needs to be triggered when the C/S end. It will handle all the resetting of the system, hud, menus, etc. It takes only one parameter bSetFinalRotation. If this flag is set, the player’s rotation will be set to match that of the CS_Wrap.
The CS_Wrap class will END ANY C/S that is active so if you are not using the bSetFinalRotation flag, your entire map needs only one CS_Wrap.
The CS_Shotlist Class
This is by far the most important class in the entire UDS codebase. It’s similar to the Unreal Dispatcher, but is designed to handle a far greater number of taskes. It’s also undergone the biggest chance since the CarnageCAM.
There are 6 important fields in the CS_ShotList class. These fields are used to actually setup the script for the sequence. Each CS_ShotList can handle 8 separate events (which I will from here on refer to as frames). The 6 fields are:
OutCamera – If a name TAG is entered in to this field, the UDS will switch the view to that camera when this frame is executed. You can change cameras as often as you like, and return to a camera after switching from it.
OutCamLock – This field locks the camera on to an object in the level. Once locked, the camera will continuously alter it’s rotation to face that object, even if the object is out of view. There are two specific tags that will cause a special action to be taken. If you enter the tag of SELF, the camera will lock on to the CSPlayer that triggered the sequence. The tag of UNLOCK will remove the lock and the camera will no longer turn towards a target.
OutTrigger – This field can be used to trigger an outside event. You should not use this to trigger other C/S actors. It can be used to trigger doors, effects and other cool stuff.
OutCommand – All other classes in the UDS are considered commands for the C/S. All UDS commands begin with the prefix “CS_”. For example, CS_OutText is a command that will output text to the display. To make the UDS do a command, you must place the Actor for the command in the level, and then add it’s name tag here. Unfortunately there seems to be no easier way to have different data sets so this is as good as any.
OUTSounds – A new sound effect can be played during each frame. Currently the sound effects are played in to the INTERFACE slot so that they retain their volume no matter the distance for the actor. Another special variable for the CS_SHOTLIST is found under SOUNDS. This variable called DialogVolume is used to determine how loud sounds coming from this CS_Shotlist should be.
OutDelays – This is the final field of the CS_Shotlist. It’s used to set the delay time between each frame. The UDS will pause for up the X.xxx seconds as found here. If you don’t wish to pause, leave this value to 0.
New to the UDS is the ability to have an event called back to the CS_Shotlist before the shotlist continues. This is currently ONLY used in player and actor movement commands, and only when a CS_SpikeTape is involoved. However it can be expanded as necessary (it’s also a big hack which I’ll clean up in time). To force the UDS to wait for a callback, simply set the OutDelay field for the frame to –1.
Multiple Shotlists
I can tell you right now, unless your trying to create something VERY small, a single shotlist will not be enough. Eight frames is simply too little to make any type of interesting scene. The UDS (like the CarnageCAM) gets around this limitation by allowing you to link Shotlists togetter. Simply add the name TAG of the next CS_Shotlist to the last OutCommand field of this current CS_ShotList. It’s that simple.
Examples
TODO: Link example level here.