5.14 Scripting Cineractives
Shot 1
Starting the Cineractive Script
Now we'll go through the same 4 shots again and look at the scripting for them in the file called "objective_destroy_shuttle.cfg". Scroll down the file in a text editor until you see the word "Cineractive". The first chunk of text looks like this:
Cineractive()
{
At(0)
{
Fade()
{
Time(1, 2, 3);
Direction("up");
}
}
What this does is initiate the cineractive and begin the fade.
Timing
The "At(0)" means that this event will happen at 0 seconds into the cineractive. Everything listed within its set of brackets will occur in that instant.
Fading
The Fade has 3 numbers listed in its "Time" field. They are explained elsewhere in the manual, but we'll go through it again quickly. In every Time field, there is a starting number that is implied. That number is the time at which the fade-out will begin, and it is always 0. The first number that appears is the time when the fade-out will end. In this case it is 1. So at 0 seconds you will have a full view, and at 1 second it will be black. The next number, 2, specifies when the fade-in will begin. And the last number, 3, specifies when the fade-in will end, returning us to an un-obscured view. The "Direction" field specifies whether we're going from light-to-dark-to-light or dark-to-light-to-dark. We will always be using the first method, so always keep the direction "up".
The purpose of this fade is to block the camera view while we switch from gameplay to the start of the cineractive. If this cineractive were appearing at the start of a mission, you would not need to fade to black at the beginning, and so your first "Time" number would be 0, followed by a 3 and then a 5, to give you a long, slow fade-in.
Triggering AI Scripts With Vars
Next comes this:
At(1)
{
Action()
{
Op("@Sprawlers_Hidden.triggerarmy", "=", 1);
}
}
The purpose of this segment is to trigger the Sprawler units to start running towards the camera in Shot 1. This script uses a simple var to trigger the move action in an AI script that is called in a separate objective. To learn how to use variables like this one, refer to the section in the manual titled "Variables". To learn how to give AI units a move order in an objective, refer to the section titled Scripting Attacks.
The objective that triggers the Sprawler units to move is in the file called "objective_start_sprawlers.cfg" under the script heading "objective_start_sprawlers_hidden". You will see that several groups of units are all running the same custom script, "squad.move.tagtoregion.wait", which is included in this mission folder. The custom script is set to give the move order the instant the "triggerarmy" var switches to 1. There are a million other considerations that need to be taken care of in order for this action to work, but the basic concept is that you are switching a var in a cineractive which triggers units to move in a separate objective. This is the key to making cool, dynamic cineractives, but it is a very difficult technique to learn and involves a great deal of scripting, and even more patience. Let's move on, shall we?
At(2)
{
DisableIFace(1);
DisableInput(1);
DisableShroud(1);
SetBookmark()
{
Name("caravan");
}
Action()
{
GameMessage()
{
Message("msg_block_ravine");
}
}
Letterbox()
{
Time(0, 44, 45);
Direction("down");
}
}
At 2 seconds, the actual cineractive begins. The fade that we executed at 0 seconds will be just starting to come up now, so we need to trigger the camera path and disable the controls.
Disabling Gameplay
The first 3 lines turn off various aspects of the game. The first is the visible interface, the second is your ability to use the interface, and the third is the map shroud. At the end of the cineractive, these 3 things will automatically be turned back on.
Triggering the Camera Path
Next comes the camera path. Use the "SetBookmark" command, then specify the name of the camera path that you created. In this case, it is the "caravan" path that we looked at earlier. This will start the path, and all the timing that you used on the nodes will begin here, at 2 seconds into the cineractive.
Note that the "caravan" camera path that we looked at in the editor was only 7 seconds long, while the next shot doesn't begin until 15 seconds into the cineractive. This leaves a 6 second gap where nothing seems to be happening. All this means is that the camera will remain static at the end of its curve for the 6 seconds until the next cut.
Using Actions
There are only a few commands that the Cineractive script understands. These are pretty much covered by "Fade", "Letterbox", "SetBookmark", "DefaultCamera", and "EndCineractive". Any command you need to give that is not one of the above must be contained with an "Action" scope. In this case, we need to give an audio game message. The use of the "Game Message" command is explained earlier in the manual.
Letterboxing
Finally, we need to trigger the letterboxing for this cineractive. We don't need to fade the letterboxing in, since it happens during total blackness, so the first number under "Time" can be 0. The next two numbers give the beginning and end of the letterboxes disappearance at the end of the cineractive. To determine these numbers, wait until you've reached the end of this script, look at the time for the "EndCineractive" command, then subtract 3 to get the first number and subtract 2 to get the second. The reason you are subtracting is because the letterboxing doesn't start until you are 2 seconds into the cineractive, and you need to give 1 second for the letterbox to fade away. The "Direction" for letterboxing will always be "Down".
At(14)
{
Fade()
{
Time(1, 1, 2);
Mode("up");
}
}
We are about to jump from Shot 1 to Shot 2, so we include this fade to smooth the transition. We start fading down 1 second before the cut, then instantaneously begin fading back up. You may notice that instead of specifying "Direction", we specify "Mode". They are one in the same and it makes no difference which you use. Move along.
Shot 2
Removing Cineractive-Only Units
At(15)
{
SetBookmark()
{
Name("DF_intro");
}
Action()
{
Delete()
{
Tag("CinAll");
}
}
}
Just as before, the "SetBookmark" command will start the next camera path going. The "Delete" command is used to remove all the Sprawler units that were running in the last shot. They are no longer in view and they are no longer needed, so it is best to remove them as soon as possible. Using "Delete" will remove them with little fanfare, using "SelfDestruct" will remove them by killing them and causing them to explode. This can be handy if you want to remove them while they're still in the frame. Also, notice that the "Delete" command is contained within and "Action" scope, since it is not recognized by the Cineractive script.
Shot 3
At(25)
{
Fade()
{
Time(1, 1, 2);
Mode("up");
}
}
At(26)
{
SetBookmark()
{
Name("DF_intro2");
}
Action()
{
ExecuteScript("Unique", "squad.move.spawntoregion")
{
Op("%.types", "=", "rigs");
Op("%.region.src", "=", "SpawnIn");
Op("%.region.dst", "=", "Rigs");
}
}
}
Triggering AI Scripts Inside the Cineractive
After a quick fade, we cut to Shot 3, which again is triggered by the "SetBookmark" command. At the same instant that the shot begins, an "Action" is created with an AI script in it. This AI script creates 3 rigs in the specified region and moves them to another region on the map. The script is actually needed for Shot 4 and is not visible in Shot 3. Spawning units onto the map through a script takes a couple seconds to carry out, so you need to trigger it well ahead of time. By the time Shot 4 begins, these 3 rigs will have spawned and begun moving on their path.
Technically, the cineractive you are running is in a script that is assigned to the player's team. As a result, units that are spawned in this objective will always be on the player's team. The Sprawler units that we spawned in Shot 1 were not on the player's team, so we couldn't create them locally. But these rigs are, so you can create them in a simple script like the one used above.
Shot 4
At(34)
{
Fade()
{
Time(1, 1, 2);
Mode("up");
}
}
At(35)
{
SetBookmark()
{
Name("rigs2");
}
}
This chunk of text fades down then up, and triggers shot 4. We've seen it all before, so let's move on.
Blending from Cineractive to Gameplay
At(45)
{
DisableShroud(0);
DefaultCamera(1)
{
Pan()
{
Region("Start");
TrackTerrain(0);
Time(1);
}
}
}
We're at the end of Shot 4 now. This is where we blend from cineractive into gameplay. First the Shroud is brought back up. This will be done automatically when the cineractive ends, but it's done manually here so that it doesn't pop up suddenly. The camera is facing down at this point and bringing the shroud up here is less noticeable.
Next comes the blend part. In a non-blending cineractive, you would only need to insert "DefaultCamera();" during a fade to black and that would bring the camera back to where it was before the cineractive began. But in this case, we need to include a "Pan" field that specifies the "Region" we want to bring the camera back to, and a "Time" that specifies how long it takes to blend from the end of the camera path to the in-game camera position. Ideally, the camera path would come pretty close to the final position, and the "Time" would only be a short duration that smoothly bridges the gap. There is also a flag called "TrackTerrain". If "TrackTerrain" is set to 1, the camera will move up and down based on the terrain it is passing over. If it is set to 0, it will ignore the terrain and do a direct blend from one point to the other. In most cases, it is best to manually set "TrackTerrain" to 0, as it defaults to 1 otherwise.
Ending the Cineractive
At(47)
{
EndCineractive();
}
}
This is the final step. "EndCineractive" turns the interface and input back on, brings up the shroud if it hasn't already been brought up, and returns you fully into the game. In the actual script, there are a bunch of other mission commands listed inside an "Action". They are irrelevant to this tutorial, however, and have been removed.