[[TOC]]

= Cinematics Tab =
Part of the [wiki:Atlas_Manual Atlas (Scenario Editor) Manual]

[[Image(https://trac.wildfiregames.com/raw-attachment/wiki/Atlas_Manual_Cinematics_Tab/cinematics_tab.png)]]

''The contents of the Cinematics Tab''

== Introduction ==

To see how the cinematics looks open the Cinema Demo map. A path of the demo map in Atlas:

[[Image(https://trac.wildfiregames.com/raw-attachment/wiki/Atlas_Manual_Cinematics_Tab/cinematics_demo.png)]]

== Terms ==
A cinematic path consists of a position and target nodes.

**Position nodes** - nodes used for the camera position.

**Target nodes** - nodes used for the camera focus position. In other words the camera looks from positions to targets.

**Delta time** - time between nodes which the camera spends to move from the one node to the other node.

== Common settings ==
The "Draw all paths" checkbox toggles cinematic paths drawing. Paths are drawing only in Atlas, and aren't drawing, when cinematics is playing. It's useful to check paths, created by triggers.

== Paths editing ==
To create a path, enter a non empty string and press the "Add" button:

[[Image(https://trac.wildfiregames.com/raw-attachment/wiki/Atlas_Manual_Cinematics_Tab/cinematics_path_save.png)]]

To remove a path, select it in the list above and press the "Delete" button. A newly created path contains 1 position (green) node with the camera position and 1 target (red) node with the camera focus position:

[[Image(https://trac.wildfiregames.com/raw-attachment/wiki/Atlas_Manual_Cinematics_Tab/cinematics_path_new.png)]]

== Node editing ==
To start editing nodes select the "Move cinema path nodes" tools (the last tool in the tool row):

[[Image(https://trac.wildfiregames.com/raw-attachment/wiki/Atlas_Manual_Cinematics_Tab/cinematics_tool.png)]]

Step 1: select any node:

[[Image(https://trac.wildfiregames.com/raw-attachment/wiki/Atlas_Manual_Cinematics_Tab/cinematics_step_0.png)]]

Step 2: press the `Insert` button on the keyboard to add a node after the currently selected node (it'll be created in the camera focus point with delta time equals to 1 second ):

[[Image(https://trac.wildfiregames.com/raw-attachment/wiki/Atlas_Manual_Cinematics_Tab/cinematics_step_1.png)]]

Step 3: pick any axis and move mouse to move the selected node:

[[Image(https://trac.wildfiregames.com/raw-attachment/wiki/Atlas_Manual_Cinematics_Tab/cinematics_step_2.png)]]

To delete a node, select it and press the `Delete` button on the keyboard. If you need to edit delta times, you could edit nodes in a map XML file (atlas editing for delta times will be added later).

== Triggers and on fly paths ==

Currently there is no way to run a cinema path without a trigger script, but this possibility will be added later.

=== Run cinema path ===

An example trigger script to run an existing cinema path in 5 seconds:

{{{
#!javascript
Trigger.prototype.StartCutscene = function(data)
{
	var cmpCinemaManager = Engine.QueryInterface(SYSTEM_ENTITY, IID_CinemaManager);
	// We should work only with valid components
	if (!cmpCinemaManager)
		return;
	// Add a cinema path with "test" name to the queue
	cmpCinemaManager.AddCinemaPathToQueue("MyPath");
	// Start playing the queue
	cmpCinemaManager.Play();
};

var cmpTrigger = Engine.QueryInterface(SYSTEM_ENTITY, IID_Trigger);
cmpTrigger.DoAfterDelay(5000, "StartCutscene", {}); // Delay is set in milliseconds
}}}

=== Add cinema path in triggers ===

{{{
#!javascript
Trigger.prototype.StartCutscene = function(data)
{
	var cmpCinemaManager = Engine.QueryInterface(SYSTEM_ENTITY, IID_CinemaManager);
	// We should work only with valid components
	if (!cmpCinemaManager)
		return;

	let pointA = new Vector3D(1, 1, 1);
	let pointB = new Vector3D(100, 100, 100);
	let path = {
		"name": "MyPath",
		"orientation": "target",
		"positionNodes": [
			{"deltaTime": 0, "position": pointA},
			{"deltaTime": 10, "position": pointB}
		],
		"targetNodes": [
			{"deltaTime": 0, "position": Vector3D.add(pointA, new Vector3D(10, 10, 0))},
			{"deltaTime": 10, "position": Vector3D.add(pointB, new Vector3D(10, 10, 0))}
		]
	};

	// Add the newly created path
	cmpCinemaManager.AddPath(path);
	cmpCinemaManager.AddCinemaPathToQueue(path.name);

	// Start playing the queue
	cmpCinemaManager.Play();
};

var cmpTrigger = Engine.QueryInterface(SYSTEM_ENTITY, IID_Trigger);
cmpTrigger.DoAfterDelay(5000, "StartCutscene", {}); // Delay is set in milliseconds
}}}