Animated Briefing – Arma 3

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Fix formatting)
m (Text replacement - "[[Image:" to "[[File:")
 
(25 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{SideTOC}}
{{TOC|side}}
The [[Arma 3 Animated Briefing]] framework allows you to create a briefing using the in-game map which features timeline-based,
The [[Arma 3: Animated Briefing]] framework allows you to create a briefing using the in-game map which features timeline-based,
animated events such as moving markers, blinking markers, zooming, and other marker-related features.
animated events such as moving markers, blinking markers, zooming, and other marker-related features.
== Features ==
* Easy to setup
* Timeline based
* Can be easily synced to music or dialogs
* Skippable




Line 18: Line 10:
The briefing can be easily synced to dialogs, such as a leader explaining a plan, or to music.
The briefing can be easily synced to dialogs, such as a leader explaining a plan, or to music.


; Features
: Easy to setup
: Timeline based
: Can be easily synced to music or dialogs
: Skippable


= Systems =


== BIS_fnc_AnimatedBriefing ==
== Systems ==


* Enhanced version of the BIS_fnc_eventTimeline function
=== [[BIS_fnc_animatedBriefing]] ===
 
* Enhanced version of the [[BIS_fnc_eventTimeline]] function
* Does the work with the event timeline simpler and get the start of the briefings consistent
* Does the work with the event timeline simpler and get the start of the briefings consistent
* It does the initial setup
* It does the initial setup
Line 31: Line 29:
** starts the event timeline by calling BIS_fnc_eventTimeline function
** starts the event timeline by calling BIS_fnc_eventTimeline function
** holdKey setup (for skipping the briefing)
** holdKey setup (for skipping the briefing)
*For the documentation visit [[BIS_fnc_animatedBriefing]].


=== Parameters ===
=== [[BIS_fnc_eventTimeline]] ===
 
{| class="wikitable"
|-
! Parameter
! Description
|-
| timeline
| 2D ARRAY: see [[BIS_fnc_eventTimeline]]
|-
| pointer
| NUMBER: see [[BIS_fnc_eventTimeline]]
|-
| music
| (OPTIONAL) - [[String]]: music to be played at the start of the briefings. Timeline events will be synced to music
|-
| hideMarkers
| (OPTIONAL) - [[Array]]: if passed, markers are hidden before starting the briefing and at the end of the briefing
|-
| showMarkers
| (OPTIONAL) - [[Array]]: array of markers which will be shown after the briefing has ended
|-
| endPosition
| (OPTIONAL) - [[String]]: marker used for determining position and size of camera at the end of the briefing
|-
| canCloseMap
| (OPTIONAL) - [[Boolean]]: value that determines whether or not the player will be able to close the map after the briefing is over
|-
| endUserCode
| (OPTIONAL) - [[Code]]: code to be executed at the end of the briefing
|}
 
 
== BIS_fnc_eventTimeline ==


* Essential system of the Animated Briefings, but the function can be used for different purposes
* Essential system of the Animated Briefings, but the function can be used for different purposes
Line 71: Line 37:
* It can play the events from start or from a defined position (index)
* It can play the events from start or from a defined position (index)
* It can be interrupted from outside
* It can be interrupted from outside
* user defined code can be executed onInterrupt or onFinished
* User defined code can be executed onInterrupt or onFinished
* See [[BIS_fnc_eventTimeline]] for full documentation


=== Parameters ===


{| class="wikitable"
== Usage ==
|-
! Parameter
! Description
|-
| timeline
| 2D ARRAY: array with keyframes and code to be activated at a certain time
|-
| pointer
| [[Number]]: where to start playing (index)
|-
| music
| (OPTIONAL) - [[String]]: music to be played which will provide the sync time for the timeline
|-
| codeInterrupt
| (OPTIONAL) - [[Code]]: code to be executed if the timeline is interrupted (missionNamespace setVariable ["BIS_fnc_eventTimeline_play", FALSE])
|-
| codeStop
| (OPTIONAL) - [[Code]] or [[Array]]: code or array of codes to be executed once the timeline is finshed. The codes are CALLed one after the other.
|}


 
=== Setup ===
= Usage =
 
== Setup ==


A few things need to be prepared before calling the Animated Briefing function:
A few things need to be prepared before calling the Animated Briefing function:
Line 109: Line 53:
** The timeline stops once it reaches the last element. The last element's code can also be empty if you're just using the element as an ending point.
** The timeline stops once it reaches the last element. The last element's code can also be empty if you're just using the element as an ending point.
** The timeline can be kept in a separate file and included using #include "timelineFile.sqf"; within the file calling the briefing.
** The timeline can be kept in a separate file and included using #include "timelineFile.sqf"; within the file calling the briefing.
<code>[[private]] _timeline = [
: <sqf>
private _timeline = [
[
[
0,
0,
{
{
[[[markerSize]] "BIS_SF_zoom0", [[markerPos]] "BIS_SF_zoom0", 0, [[nil]], [[true]]] [[spawn]] [[BIS_fnc_zoomOnArea]];
[markerSize "BIS_SF_zoom0", markerPos "BIS_SF_zoom0", 0, nil, true] spawn BIS_fnc_zoomOnArea;
[([[getMissionLayerEntities]] "g_showAtEnd") [[select]] 1, 0, [[true]]] [[spawn]] [[BIS_fnc_showMarkerArray]];<br>
[(getMissionLayerEntities "g_showAtEnd") select 1, 0, true] spawn BIS_fnc_showMarkerArray;
[[sleep]] 0.5;<br>
 
[[[markerSize]] "BIS_SF_zoom1", [[markerPos]] "BIS_SF_zoom1", 3, [[nil]], [[true]]] [[spawn]] [[BIS_fnc_zoomOnArea]];
sleep 0.5;
 
[markerSize "BIS_SF_zoom1", markerPos "BIS_SF_zoom1", 3, nil, true] spawn BIS_fnc_zoomOnArea;
}
}
],
],
Line 122: Line 69:
1.5,
1.5,
{
{
["to_c02_m01_003_br_sf_briefing_c_GUARDIAN_0", "GUARDIAN", BIS_fnc_AnimatedBriefing_speaker1] [[spawn]] [[BIS_fnc_TO_playSoundAndSubtitles]];<br>
["to_c02_m01_003_br_sf_briefing_c_GUARDIAN_0", "GUARDIAN", BIS_fnc_AnimatedBriefing_speaker1] spawn BIS_fnc_TO_playSoundAndSubtitles;
["BIS_SF_specialArea", 2] [[spawn]] [[BIS_fnc_showMarker]];
 
["BIS_SF_specialArea", 2] spawn BIS_fnc_showMarker;
}
}
],
],
Line 129: Line 77:
8.2,
8.2,
{
{
["to_c02_m01_003_br_sf_briefing_c_GUARDIAN_1", "GUARDIAN", BIS_fnc_AnimatedBriefing_speaker1] [[spawn]] [[BIS_fnc_TO_playSoundAndSubtitles]];<br>
["to_c02_m01_003_br_sf_briefing_c_GUARDIAN_1", "GUARDIAN", BIS_fnc_AnimatedBriefing_speaker1] spawn BIS_fnc_TO_playSoundAndSubtitles;
_arrayTemp = ["BIS_SF_question_"] [[call]] [[BIS_fnc_getMarkers]];
 
[_arrayTemp, 8, [[false]]] [[spawn]] [[BIS_fnc_showMarkerArray]];
_arrayTemp = ["BIS_SF_question_"] call BIS_fnc_getMarkers;
[_arrayTemp, 8, false] spawn BIS_fnc_showMarkerArray;
}
}
],
],
[ 12, {}]
[ 12, {}]
];</code>
];
</sqf>


* '''Array of markers to be hidden'''
* '''Array of markers to be hidden'''
Line 143: Line 93:
* '''Array of markers to be shown at the end of the Briefing'''
* '''Array of markers to be shown at the end of the Briefing'''
** Array of markers that will be shown at the end of the briefing.
** Array of markers that will be shown at the end of the briefing.
** Markers that are manually shown during timeline events should also be included, as skipping the briefing before those events occur won't show them if they aren't.
** Markers that are manually shown during timeline events should also be included, as skipping the briefing before those events occur won't show them if they are not.
** Markers can be organized into layers to facilitate the usage of the Animated Briefing function. <br>[[Image:A3_animBrief_layers.JPG|400px]]
** Markers can be organized into layers to facilitate the usage of the Animated Briefing function. <br>[[File:A3_animBrief_layers.JPG|400px]]
*** To show the contents of the "showAtEnd" layers at the end of the Briefing, you can use the following code when calling the Animated Briefing function:
*** To show the contents of the "showAtEnd" layers at the end of the Briefing, you can use the following code when calling the Animated Briefing function:
<code>[_timeline, 0[[,]] nil, [[allMapMarkers]], ([[getMissionLayerEntities]] "showAtEnd") [[select]] 1, "BIS_markerh_Zoom_final"] [[spawn]] [[BIS_fnc_AnimatedBriefing]];</code>
<sqf>[_timeline, 0, nil, allMapMarkers, (getMissionLayerEntities "showAtEnd") select 1, "BIS_markerh_Zoom_final"] spawn BIS_fnc_animatedBriefing;</sqf>


To show a list of markers when the briefing starts, retrieve and show them in the first element of the timeline at 0 seconds as shown below:
To show a list of markers when the briefing starts, retrieve and show them in the first element of the timeline at 0 seconds as shown below:
<code>[[private]] _timeline =
<sqf>
private _timeline =
[
[
[
[
0,
0,
{
{
[([[getMissionLayerEntities]] "showAtStart") [[select]] 1, 0, [[true]]] [[spawn]] [[BIS_fnc_showMarkerArray]];
[(getMissionLayerEntities "showAtStart") select 1, 0, true] spawn BIS_fnc_showMarkerArray;
}
}
],
],
...</code>
// etc
];
</sqf>


* '''Camera size and position at the end of the Briefing'''
* '''Camera size and position at the end of the Briefing'''
Line 164: Line 117:
** Rectangle markers can be used to make it easier to find the right position and size.
** Rectangle markers can be used to make it easier to find the right position and size.


 
=== Starting the Briefing ===
== Starting the Briefing ==


The Animated Briefing can be started by calling the function BIS_fnc_AnimatedBriefing. Once called, the briefing starts right away.
The Animated Briefing can be started by calling the function BIS_fnc_AnimatedBriefing. Once called, the briefing starts right away.


<code>{{cc|timeline of events}}
<sqf>
// timeline of events
_timeline =
_timeline =
[
[
[0.0, { [[hint]] "Start of the Timeline" } ],
[0.0, { hint "Start of the Timeline" } ],
[1.0, { [[hint]] "Event 1" } ],
[1.0, { hint "Event 1" } ],
[3.0, { [[hint]] "End of the timeline" } ]
[3.0, { hint "End of the timeline" } ]
];<br>
];
{{cc|get markers to be shown at end by using the layer's name}}
 
[[private]] _showMarkers = ([[getMissionLayerEntities]] "showAtEnd") [[select]] 1;<br>
// get markers to be shown at end by using the layer's name
{{cc|start the Animated Briefing at index 0}}
private _showMarkers = (getMissionLayerEntities "showAtEnd") select 1;
{{cc|hide all markers and show the markers from the "showAtEnd" layer after the briefing is done}}
 
{{cc|zoom on marker_rect_1 at the end of the briefing}}
// start the Animated Briefing at index 0
[_timeline, 0, [[nil]], [[allMapMarkers]], _showMarkers, "marker_rect_1"] [[spawn]] [[BIS_fnc_AnimatedBriefing]];<br>
// hide all markers and show the markers from the "showAtEnd" layer after the briefing is done
{{cc|Wait until timeline is over}}
// zoom on marker_rect_1 at the end of the briefing
[[waitUntil]] { !([[missionNamespace]] [[getVariable]] "BIS_fnc_eventTimeline_playing"); };
[_timeline, 0, nil, allMapMarkers, _showMarkers, "marker_rect_1"] spawn BIS_fnc_animatedBriefing;
</code>


{{Informative |
// Wait until timeline is over
waitUntil { !(missionNamespace getVariable "BIS_fnc_eventTimeline_playing"); };
</sqf>
 
{{Feature|informative|
* The briefing can be started from a different keyframe (by passing the pointer/index), which is helpful in the development/testing phase.
* The briefing can be started from a different keyframe (by passing the pointer/index), which is helpful in the development/testing phase.
* The briefing can be interrupted by setting a variable: {{Inline code| [[missionNamespace]] [[setVariable]] ["BIS_fnc_eventTimeline_play", [[false]]]}}
* The briefing can be interrupted by setting a variable: <sqf inline>missionNamespace setVariable ["BIS_fnc_eventTimeline_play", false]</sqf>.
* To hide the standard briefing screen that normally opens after the Intro phase ends, add the line {{Inline code|briefing = 0;}} in the [[Description.ext]] file in your mission folder.
* To hide the standard briefing screen that normally opens after the Intro phase ends, add the line <syntaxhighlight lang="cpp" inline>briefing = 0;</syntaxhighlight> in the [[Description.ext]] file in your mission folder.
}}
}}


== Synchronizing a timeline to dialogues ==
=== Synchronizing a timeline to dialogues ===


Dialogues can be easily synchronized to events. This can be achieved by following these steps:
Dialogues can be easily synchronized to events. This can be achieved by following these steps:
Line 201: Line 157:
* Write down the starting times of each one of your dialogues or, alternatively, create labels and place them at the beginning of each dialogue and then export them.
* Write down the starting times of each one of your dialogues or, alternatively, create labels and place them at the beginning of each dialogue and then export them.
* Create an .sqf file with a timeline array using these times (in seconds).
* Create an .sqf file with a timeline array using these times (in seconds).
** Use the following example to create a timeline:
** Use the following example to create a timeline: <sqf>
<code>[[private]] _timeline =
private _timeline =
[
[
[
[
Line 215: Line 171:
],
],
[ 12, {}]
[ 12, {}]
];</code>
];
</sqf>
* Set up audio files so they can be played from the timeline.
* Set up audio files so they can be played from the timeline.
** Set them up in the CfgSounds class. <syntaxhighlight lang="cpp">class CfgSounds
** Set them up in the CfgSounds class. <syntaxhighlight lang="cpp">
class CfgSounds
{
{
// Little Hope Mission 02
// Little Hope Mission 02
Line 236: Line 194:
};
};
...
...
};</syntaxhighlight>
};
</syntaxhighlight>
* Add commands to play the dialogs in the timeline you just created.
* Add commands to play the dialogs in the timeline you just created.
** It is recommended to use BIS_fnc_playSoundAndSubtitles or say2D.
** It is recommended to use [[BIS_fnc_playSoundAndSubtitles]] or [[say2D]].
** Note that the Animated Briefing functions creates two speaker objects, BIS_fnc_AnimatedBriefing_speaker1 and BIS_fnc_AnimatedBriefing_speaker2, which should be used to play dialogues or SFX pertaining the Animated Briefing. {{Inline code|["to_c01_m01_brief_002_br_briefing_b_OLYMPOS_0", "OLYMPOS", BIS_fnc_AnimatedBriefing_speaker1] [[call]] [[BIS_fnc_TO_playSoundAndSubtitles]];}}
** Note that the Animated Briefing functions creates two speaker objects, BIS_fnc_AnimatedBriefing_speaker1 and BIS_fnc_AnimatedBriefing_speaker2, which should be used to play dialogues or SFX pertaining the Animated Briefing. <sqf>["to_c01_m01_brief_002_br_briefing_b_OLYMPOS_0", "OLYMPOS", BIS_fnc_AnimatedBriefing_speaker1] call BIS_fnc_TO_playSoundAndSubtitles;</sqf>
* Add a final element to the timeline array with the ending time.
* Add a final element to the timeline array with the ending time.


Once you are done with creating the timeline, you can add commands (e.g.: moving/showing/resizing markers) to the existing timeline elements to have them synchronized with the dialogs.
Once you are done with creating the timeline, you can add commands (e.g moving/showing/resizing markers) to the existing timeline elements to have them synchronized with the dialogs.
 
= Map and Marker Functions =
 
== Map and zoom-related functions ==
 
{| class="wikitable"
|-
! Name
! Description
! Parameters
! Returns
! Example
|-
| BIS_fnc_zoomOnArea
| Rectangular area markers can be used as the parameter.
|
* ARRAY: Area to zoom on
* ARRAY: Coordinates of the center
* (OPTIONAL) - NUMBER: time of the zoom operation. Default is 1
* (OPTIONAL) - CONTROL: handler to the map display control (you can pass one if already exists, if not, handler is created)
* (OPTIONAL) - BOOL: whether we have to force the camera in position after the zoom.
|
|
|-
| BIS_fnc_shakeMap
| "Camera shake" function for the map. Shakes the map for a given amount of time with a given amount of force around the given camera center.
|
* Select 0 - NUMBER: duration of shake effect.
* NUMBER: magnitude of the shaking force.
* ARRAY: position of the camera center around which the shake effect occurs.
|
| [2,20,getMarkerPos "BIS_markerExtraction0"] call BIS_fnc_shakeMap;
|-
| BIS_fnc_shakeMapEH
| Event handler function called by the shakeMap function.
|
* Select 0 - NUMBER: duration of shake effect.
* NUMBER: magnitude of the shaking force.
* ARRAY: position of the camera center around which the shake effect occurs.
* NUMBER: starting shake time (i.e. time elapsed since mission started till the start of the shake animation).
|
|
|-
| BIS_fnc_zoomLock
| Function that locks the camera in place when the map is open.
|
* ARRAY: position where the camera should be placed and locked
|
| [_cameraCenter] call BIS_fnc_zoomLock;
|-
| BIS_fnc_zoomLockEH
| Event handler function for locking the camera.
|
* ARRAY: position where the camera should be placed and locked
|
|
|-
| BIS_fnc_zoomUnlock
| Function that unlocks the camera in which has been previously locked with BIS_fnc_zoomLock.
|
|
| [] call BIS_fnc_zoomUnlock;
|}


== Marker-related functions ==


{| class="wikitable"
== Map and Marker Functions ==
|-
! Name
! Description
! Parameters
! Returns
! Example
|-
| BIS_fnc_blinkMarker
| Blinks a marker (shows and hides it in sequence)
|
* STRING: Marker
* (OPTIONAL) - NUMBER: Duration of blinking
* (OPTIONAL) - NUMBER: Number of blinks
|
| ["BIS_marker", 3, 10] spawn BIS_fnc_blinkMarker;
|-
| BIS_fnc_getBorderMarkers
| Retrieves marker names used in the border restrictions module
|
|
* ARRAY: list of markers
| _borderMarkers = [] spawn BIS_fnc_getBorderMarkers;
|-
| BIS_fnc_showMarker
| Shows marker. If speed is not passed, the default is used. If final marker is not passed, then marker's alpha is restored to last recorded alpha (i.e.: marker's alpha before it was hidden).
|
* STRING: Marker.
* (OPTIONAL) - NUMBER: Duration of revealing
* (OPTIONAL) - NUMBER: final marker alpha
|
| ["BIS_marker"] spawn BIS_fnc_showMarker;["BIS_marker",2] spawn BIS_fnc_showMarker;
|-
| BIS_fnc_hideMarker
| Hides marker. If speed is not passed, the default is used.
|
* STRING: Marker
* (OPTIONAL) - NUMBER: Duration of hiding, default is 1.
|
|
["BIS_marker"] spawn BIS_fnc_hideMarker;
["BIS_marker",2] spawn BIS_fnc_hideMarker;
|-
| BIS_fnc_cancelMarker
| Places a red "X" marker on top of a specified marker.
|
* STRING: Marker
* (OPTIONAL) - NUMBER: Duration of canceling, default is 1
* (OPTIONAL) - NUMBER: After how long should the X fade out
* (OPTIONAL) - NUMBER: Multiplier for a size of the 'cancel' marker compared to the original, default is 1
* (OPTIONAL) - NUMBER: Angle offset from the original marker, default is 45
|
|
["BIS_marker"] spawn BIS_fnc_cancelMarker;
["BIS_marker",2] spawn BIS_fnc_cancelMarker;
["BIS_marker",2,1.5] spawn BIS_fnc_cancelMarker;
["BIS_marker",2,1.5,75] spawn BIS_fnc_cancelMarker;
|-
| BIS_fnc_rotateMarker
| Rotates marker by a given degree (relative or absolute). If speed is not passed, the default is used
|
* STRING: Marker
* NUMBER: New azimuth
* (OPTIONAL) - BOOLEAN: Absolute (true) or relative (false) azimuth (default true)
* (OPTIONAL) - NUMBER: 0 - shortest turn (default, if used with relative dir, counter clockwise is used), 1 - force clockwise, 2 - force counter clockwise
* (OPTIONAL) - NUMBER: Duration for complete rotation (default 2)
|
|
["BIS_marker",90] spawn BIS_fnc_rotateMarker;
["BIS_marker",90,false] spawn BIS_fnc_rotateMarker;
["BIS_marker",90,true,1] spawn BIS_fnc_rotateMarker;
["BIS_marker",90,false,2,5] spawn BIS_fnc_rotateMarker;
|-
| BIS_fnc_moveMarker
| Moves marker from point A to point B. Several types of interpolation can be used for the movement.
|
* STRING: Marker
* ARRAY: New position
* NUMBER: Duration
* NUMBER: Type of interpolation
** <small>LINEAR: 0</small>
** <small>CUBIC: 1</small>
** <small>EASEIN: 2</small>
** <small>EASEOUT: 3</small>
** <small>EASEINOUT: 4</small>
** <small>HERMITE: 5</small>
** <small>BERP: 6</small>
** <small>BOUNCEIN: 7</small>
** <small>BOUNCEOUT: 8</small>
** <small>BOUNCEINOUT: 9</small>
** <small>QUINTICIN: 10</small>
** <small>QUINTICOUT: 11</small>
** <small>QUINTICINOUT: 12</small>
** <small>CONSTANT: 13</small>
|
|
["BIS_marker",[1111,2222,0]] call BIS_fnc_moveMarker;
["BIS_marker",(getMarkerPos "BIS_marker2"),2] call BIS_fnc_moveMarker;
|-
| BIS_fnc_resizeMarker
| Resize marker to new size.
|
* STRING: Marker
* ARRAY: Size [x-axis, y-axis]
* (OPTIONAL) - NUMBER: Duration of resizing, default is 1
|
|
["BIS_marker",[2,2]] spawn BIS_fnc_resizeMarker;
["BIS_marker",[5,5],5] spawn BIS_fnc_resizeMarker;
|-
| BIS_fnc_changeColorMarker
| Makes the marker go from its original color to a specified color over time.
|
* STRING: Marker
* STRING: Color
* (OPTIONAL) - NUMBER: Duration of transition, default is 1
|
|
["BIS_marker",[2,2]] spawn BIS_fnc_resizeMarker;
["BIS_marker",[5,5],5] spawn BIS_fnc_resizeMarker;
|-
| BIS_fnc_colorMarker
| Colors marker using a transition.
|
* STRING: Marker
* STRING: Color
* (OPTIONAL) - NUMBER: Duration of transition, default is 1
|
|
["BIS_marker","ColorRed"] spawn BIS_fnc_colorMarker;


|-
See [[:Category: Function Group: Map and Markers| Function Group: Map and Markers]].
| BIS_fnc_getMarkerState
| Get the visibility state of the marker.
|
* STRING: Marker
|
* STRING: hidden / shown / canceled
|
_state = "BIS_marker" call BIS_fnc_getMarkerState;
|-
| BIS_fnc_showMarkerArray
| Shows a set of markers. You can show and hide them sequentially by passing false as the 3rd parameter
|
* ARRAY: Markers array
* NUMBER: Duration of whole sequence
* BOOL: Keep markers displayed or hide them after showing
|
|[BIS_alphaMovementArray, 3.0, false] spawn BIS_fnc_showMarkers;
|-
| BIS_fnc_hideMarkerArray
| Hide markers over time or instantly.
|
* ARRAY: Markers array
* NUMBER: Duration of whole sequence
|
|[_arrayTemp, 2] spawn BIS_fnc_hideMarkerArray;
|-
| BIS_fnc_getMarkers
| Helper function. Gets all markers starting with the prefix passed as parameter
|
* STRING: Marker's prefix
|
* ARRAY: Markers array
|_markers = ["BIS_fia_arrow_"] call BIS_fnc_getMarkers;
|}




[[Category:Arma 3: Editing]]
{{GameCategory|arma3|Tutorials}}
[[Category:Briefing]]

Latest revision as of 23:10, 20 November 2023

The Arma 3: Animated Briefing framework allows you to create a briefing using the in-game map which features timeline-based, animated events such as moving markers, blinking markers, zooming, and other marker-related features.


Functionality

The standard map is used as the platform. Standard markers are placed on the map using some kind of animations. Showing, hiding, canceling, moving and stretching markers is done by set of functions which are part of the briefing's framework. The briefing can be easily synced to dialogs, such as a leader explaining a plan, or to music.

Features
Easy to setup
Timeline based
Can be easily synced to music or dialogs
Skippable


Systems

BIS_fnc_animatedBriefing

  • Enhanced version of the BIS_fnc_eventTimeline function
  • Does the work with the event timeline simpler and get the start of the briefings consistent
  • It does the initial setup
    • speaker setup
    • black-out / black-in
    • opens the map
    • starts the event timeline by calling BIS_fnc_eventTimeline function
    • holdKey setup (for skipping the briefing)
  • For the documentation visit BIS_fnc_animatedBriefing.

BIS_fnc_eventTimeline

  • Essential system of the Animated Briefings, but the function can be used for different purposes
  • It executes the code fragments at given time (keyframes)
  • It can play the events from start or from a defined position (index)
  • It can be interrupted from outside
  • User defined code can be executed onInterrupt or onFinished
  • See BIS_fnc_eventTimeline for full documentation


Usage

Setup

A few things need to be prepared before calling the Animated Briefing function:

  • Timeline
    • A timeline is a multi-dimensional array in which each element consists of a time (represented by a number) and an event (a piece of code).
    • The timeline starts counting from 0 when it is created.
    • When the time specified in a timeline's element has elapsed, its relative event is spawned.
    • The timeline stops once it reaches the last element. The last element's code can also be empty if you're just using the element as an ending point.
    • The timeline can be kept in a separate file and included using #include "timelineFile.sqf"; within the file calling the briefing.
private _timeline = [ [ 0, { [markerSize "BIS_SF_zoom0", markerPos "BIS_SF_zoom0", 0, nil, true] spawn BIS_fnc_zoomOnArea; [(getMissionLayerEntities "g_showAtEnd") select 1, 0, true] spawn BIS_fnc_showMarkerArray; sleep 0.5; [markerSize "BIS_SF_zoom1", markerPos "BIS_SF_zoom1", 3, nil, true] spawn BIS_fnc_zoomOnArea; } ], [ 1.5, { ["to_c02_m01_003_br_sf_briefing_c_GUARDIAN_0", "GUARDIAN", BIS_fnc_AnimatedBriefing_speaker1] spawn BIS_fnc_TO_playSoundAndSubtitles; ["BIS_SF_specialArea", 2] spawn BIS_fnc_showMarker; } ], [ 8.2, { ["to_c02_m01_003_br_sf_briefing_c_GUARDIAN_1", "GUARDIAN", BIS_fnc_AnimatedBriefing_speaker1] spawn BIS_fnc_TO_playSoundAndSubtitles; _arrayTemp = ["BIS_SF_question_"] call BIS_fnc_getMarkers; [_arrayTemp, 8, false] spawn BIS_fnc_showMarkerArray; } ], [ 12, {}] ];
  • Array of markers to be hidden
    • Array of markers that will be hidden both at the start of the briefing and at the end.
    • You can use allMapMarkers to hide every marker.
  • Array of markers to be shown at the end of the Briefing
    • Array of markers that will be shown at the end of the briefing.
    • Markers that are manually shown during timeline events should also be included, as skipping the briefing before those events occur won't show them if they are not.
    • Markers can be organized into layers to facilitate the usage of the Animated Briefing function.
      A3 animBrief layers.JPG
      • To show the contents of the "showAtEnd" layers at the end of the Briefing, you can use the following code when calling the Animated Briefing function:

[_timeline, 0, nil, allMapMarkers, (getMissionLayerEntities "showAtEnd") select 1, "BIS_markerh_Zoom_final"] spawn BIS_fnc_animatedBriefing;

To show a list of markers when the briefing starts, retrieve and show them in the first element of the timeline at 0 seconds as shown below:

private _timeline = [ [ 0, { [(getMissionLayerEntities "showAtStart") select 1, 0, true] spawn BIS_fnc_showMarkerArray; } ], // etc ];

  • Camera size and position at the end of the Briefing
    • Position and size the camera will jump to at the end of the briefing
    • This helps ensure that the camera will be in the same position when the briefing ends both if the player watches through or skips the Briefing.
    • Rectangle markers can be used to make it easier to find the right position and size.

Starting the Briefing

The Animated Briefing can be started by calling the function BIS_fnc_AnimatedBriefing. Once called, the briefing starts right away.

// timeline of events _timeline = [ [0.0, { hint "Start of the Timeline" } ], [1.0, { hint "Event 1" } ], [3.0, { hint "End of the timeline" } ] ]; // get markers to be shown at end by using the layer's name private _showMarkers = (getMissionLayerEntities "showAtEnd") select 1; // start the Animated Briefing at index 0 // hide all markers and show the markers from the "showAtEnd" layer after the briefing is done // zoom on marker_rect_1 at the end of the briefing [_timeline, 0, nil, allMapMarkers, _showMarkers, "marker_rect_1"] spawn BIS_fnc_animatedBriefing; // Wait until timeline is over waitUntil { !(missionNamespace getVariable "BIS_fnc_eventTimeline_playing"); };

  • The briefing can be started from a different keyframe (by passing the pointer/index), which is helpful in the development/testing phase.
  • The briefing can be interrupted by setting a variable: missionNamespace setVariable ["BIS_fnc_eventTimeline_play", false].
  • To hide the standard briefing screen that normally opens after the Intro phase ends, add the line briefing = 0; in the Description.ext file in your mission folder.

Synchronizing a timeline to dialogues

Dialogues can be easily synchronized to events. This can be achieved by following these steps:

  • Open your dialog audio file or files in an audio editing software
  • Organize/place them as you would like to hear them.
    • Waiting roughly 1.5 seconds before playing any dialogue is recommended as there is a slow fade in at the beginning of the Animated Briefing.
  • Write down the starting times of each one of your dialogues or, alternatively, create labels and place them at the beginning of each dialogue and then export them.
  • Create an .sqf file with a timeline array using these times (in seconds).
    • Use the following example to create a timeline:
      private _timeline = [ [ 1.5, { } ], [ 8.2, { } ], [ 12, {}] ];
  • Set up audio files so they can be played from the timeline.
    • Set them up in the CfgSounds class.
      class CfgSounds
      {
      	// Little Hope Mission 02
      	class to_c01_m02_brief_01
      	{
      		sound[] = {"\a3\Dubbing_F_Tacops\Briefings\to_c01_m02\to_c01_m02_brief_01.ogg", db+3,1};
      		titles[] = {};
      	};
      	class to_c01_m02_brief_02
      	{
      		sound[] = {"\a3\Dubbing_F_Tacops\Briefings\to_c01_m02\to_c01_m02_brief_02.ogg", db+3,1};
      		titles[] = {};
      	};
      	class to_c01_m02_brief_03
      	{
      		sound[] = {"\a3\Dubbing_F_Tacops\Briefings\to_c01_m02\to_c01_m02_brief_03.ogg", db+3,1};
      		titles[] = {};
      	};
      	...
      };
      
  • Add commands to play the dialogs in the timeline you just created.
    • It is recommended to use BIS_fnc_playSoundAndSubtitles or say2D.
    • Note that the Animated Briefing functions creates two speaker objects, BIS_fnc_AnimatedBriefing_speaker1 and BIS_fnc_AnimatedBriefing_speaker2, which should be used to play dialogues or SFX pertaining the Animated Briefing.
      ["to_c01_m01_brief_002_br_briefing_b_OLYMPOS_0", "OLYMPOS", BIS_fnc_AnimatedBriefing_speaker1] call BIS_fnc_TO_playSoundAndSubtitles;
  • Add a final element to the timeline array with the ending time.

Once you are done with creating the timeline, you can add commands (e.g moving/showing/resizing markers) to the existing timeline elements to have them synchronized with the dialogs.


Map and Marker Functions

See Function Group: Map and Markers.