The ACE3 spectator system is designed to act as a flexible and easy to configure framework. Most scenarios can be set up as desired using only the settings provided, however public functions are available for finer control of these configurable aspects.
By default, the ACE3 spectator system does nothing - meaning existing missions will behave exactly as before. There are two tools available to enable the spectator system in your missions:
- An `"ace_spectator"` [respawn template](https://community.bistudio.com/wiki/Arma_3_Respawn)
- Public functions `ace_spectator_fnc_setSpectator` and `ace_spectator_fnc_stageSpectator`
With respawn template `"ace_spectator"` in effect players will enter spectator mode upon death and exit upon respawn. The template is compatible with all respawn types and allows you to take advantage of the vanilla framework's flexibility (combining templates, side specific templates, etc.). This makes for very simple combination of a wide variety of spectator and respawn setups.
For groups using custom respawn frameworks - or for missions where you want finer control over who, how and when players enter spectator - the two following functions are provided:
`ace_spectator_fnc_setSpectator`
```
* Sets local client to the given spectator state (virtually)
* To physically handle a spectator see ace_spectator_fnc_stageSpectator
*
* Client will be able to communicate in ACRE/TFAR as appropriate
* The spectator interface will be opened/closed
*
* Arguments:
* 0: Spectator state of local client <BOOL> (default: true)
*
* Return Value:
* None <NIL>
*
* Example:
* [true] call ace_spectator_fnc_setSpectator
```
`ace_spectator_fnc_stageSpectator`
```
* Sets target unit to the given spectator state (physically)
* To virtually handle a spectator see ace_spectator_fnc_setSpectator
*
* Units will be gathered at marker ace_spectator_respawn (or [0,0,0] by default)
* Upon unstage, units will be moved to the position they were in upon staging
*
* Arguments:
* 0: Unit to put into spectator stage <OBJECT> (default: player)
Spectatable units are stored in an automatically maintained list (`ace_spectator_unitList`) on each client. However, directly accessing this list is not encouraged. Instead mission makers have two tools at their disposal to tweak the list:
The unit filter determines which units will automatically be used to populate the spectatable unit list. It's controlled by setting `ace_spectator_filterUnits` and there are four possible options:
In cases where more specific control is required function `ace_spectator_fnc_updateUnits` can be used to whitelist units from the filter or blacklist them from the list (on the local client):
Spectatable sides can simply be considered an extra layer of filtering for the spectatable unit list. Again, there are two methods of controlling the spectatable sides:
The side list is exactly what it sounds like, a list of sides spectatable by the local client. However, unlike spectatable units the side list remains static and can only be updated manually. This is because the side filter is applied on top of the side list whenever the unit list is automatically maintained - meaning the unit list will update if the player changes side or if the side relations change.
The default side list is `[west,east,resistance,civilian]` and to update it (on the local client) function `ace_spectator_fnc_updateSpectatableSides` can be used:
The side filter determines which sides from the side list are valid each time the unit list is updated. It's controlled by setting `ace_spectator_filterSides` and there are four possible options:
Mission makers can control the camera modes available to spectators via the setting `ace_spectator_restrictModes`. Function `ace_spectator_fnc_updateCameraModes` is also provided to alter the available modes (to the local player) as desired at any point in the mission:
Mission makers can control which of these vision modes are available to spectators via the setting `ace_spectator_restrictVisions`. However, there are actually a total of 10 possible vision modes and function `ace_spectator_fnc_updateVisionModes` can be used to alter which of them are available (to the local player) at any point in the mission:
Function `ace_spectator_fnc_setCameraAttributes` can be used to change any of these attributes at ay point (including before spectator has ever opened):
The map overlay will show the current position of the free camera and all spectatable units. In free camera you can alt-click on the map to teleport the camera to the position of the cursor.
