Arma3_Epoch/ACE3
1
0
Fork 0
mirror of https://github.com/acemod/ACE3.git synced 2024-08-30 18:23:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update spectator docs (#5362)

Browse Source 
* Add player initilization safety to setSpectator

Public function which should wait for player unit to exist before running.
With this change an additional variable is now set on the player unit which
can be used to check whether players are spectators or not (part of
grander plans).

* Add UI initalization safety to setSpectator

Should make it so that calling the public function before the main display
has initalized will correctly wait until it has before starting spectator

* Overhaul spectator

Initial WIP overhaul of spectator component. Based on BI's End Game
Spectator and AACO's work on POTATO spectate. The essential functionality
is in place, but some things are broken and some are still to be
transferred.

* Remove redundant canInteract condition

Spectator UI will be open anyway so this is pointless.

* Fix follow camera controls

Also ensure unit camera modes have a target more consistently

* Fix widget weapon icon for unarmed

* Fix follow camera zooming

* Fix entity list not updating correctly

* Remove redundant conditions

* Fix list click behaviour

* Remove a bunch of old debug

* Alter behaviour of camera speed

* Restructure the spectator addon

* Fix camera tracking behaviour

* Fix very fast camera toggle

* Fix initial camera mode

* Fix double click behaviour

* Make AI name display consistent

* Add UI toggle

* Fix current camera mode button highlighting

* Fix focus info widget when clicked on in 3D world

* Improve key handling

Use of `inputAction` could result in weirdness when multiple keys pressed
at the same time. Hardcoded for now.

* Implement dynamic help UI element

* Remove some redundant code

* Fix follow camera jitter

* Add projectile drawing

Technically the capability to draw projectiles has been in since the
start. However it took me a bit of time to figure out how best to
add/remove the required event handlers.

I decided to add them during the process of finding things to draw, since
I'm iterating over the list of spectatable entities here anyway. With an
additional GVAR containing up to date entities, the fired EHs can remove
themselves when applicable. This avoids any granularity issues with adding
EHs en masse.

* Improve naming convention related to drawing

* Remove outdated unit and side settings

Also re-add unit whitelisting/blacklisting support

* Rename public function for consistency

Adds a deprecated warning to the old function name.

* Update stringtable

Some entries are replaced with BI translations, others are no longer
needed. I pieced together one of the camera mode settings by combining the
BI translations of the individual versions.

* Add location public functions and list population

Just need to take care of drawing and then camera interaction now

* Add location 2D and 3D drawing

* Respect whitelist and blacklist correctly

* Add location camera focus capability

* Fix local helicopters follow mode bug

* Add compatibility with `counter` template

Simply repositions the counter UI to the top of the screen out of the way

* Update respawn template

This template is only compatible with respawn types 2 & 3

* Rename compatibility function

* Add compatibility for respawn types 1,4 and 5

* Update setCameraAttributes function

* Fix draw3D for respawn types 1,4 and 5

* Fix screeching seagulls #4265

* Fix script command typo

* SQF Linter Pass

* Add obsolete warning for public func params

* Deprecate interrupt function

* Fix incorrect function call

* Make playable virtual spectator work

* Improve focus handling in public function

- User might want to reset focus for free cam, in which case objNull
  cannot be reserved for random
- Focus is still required for unit camera
- Update some function headers

* Note explicitly the use of `player`

* Remove unused base classes

* Improve seagull culling

* Add projectile drawing to vehicles

* Fix same tab selection clearing list

* Make projectile lines last 1 frame longer

* Add true zeus compatibility

- Re-opens spectator when zeus closes
- Transfers the curator module over in the respawn template
- Only handle uiForced in setSpectator to avoid issues with esc key
- Add safety to setFocus so that it only updates the UI when applicable

* Fix player moving in FPP

* Fix zeus transfer and re-opening

* Consolidate icon definitions

* Fix AI setting for player groups

* Improve handling of alive spectators

Instead of disabling simulation, just stage them automatically if alive.

* Fix respawn template for types 2 & 3

* Fix pre-set camera mode with no focus

- Improve handling of UI updates in camera related functions
- More explicit UI initalisation
- Find a focus if one wasn't pre-set for a camera mode which requires a
  focus

* Localise key names

* Fix camera mode and vision settings on init

When spectator starts the available camera modes and vision modes should
be consulted to ensure they are respected upon opening.

* Fix key localisation

* Add next/prev entity keys

* Fix vision modes update while camera active

- Updates the camera vision mode in case the current was removed

* Add public getCameraAttributes function

* Fix spectator zeus compatibility

- Camera control wasn't returned on exit due to change in fnc_ui

* Improve vision mode handling

- Curator now resets vision mode on entry
- First person also reset vision mode so that it is consistent between
  camera changes

* Improve location handling

- It makes more sense to specifiy the position ATL since the text is going
  to be rendered there and a z of 0 is then ground height.
- Updates the ui immediately if the list is already on locations

* Disable list keyboard search

* Fix handling of forced camera mode with no focus

* Fix handling of free mode removal while no target

* Fix locations respecting available modes

* Fix list entry removal code

- Replace getTargetGroups with getTargetEntities for consolidated
  filtering.
- Fix the step of the removal loops and make them go to index 0 instead of
  1

* Improve side handling of unit list

- Accounts for possibly of whitelisted random objects that belong to other
  sides
- Move the index decrement to loop, not within every loop

* Add linter ignore directive

* Fix list code

* Improve entity fetching

- Change whitelist/blacklist application to optimize the code

* Include dead units in the list

- Allow getTargetEntities to return dead units too
- Iterate over allGroups in list updates to reduce overhead

* Take care of TODOs

* Mark stageSpectator as non-public

* Fix updating list focus

* Adjust default camera speed

* Include the function file

* Generalise camera button UI

- Makes it easier to extend with future camera mode buttons
- Removes potential error when display doesn't exist

* Remove obsolete staged event

- Add vision toggle to help
- Restructure some function PREP

* Add public function to return all spectators

* Change default briefing name used on map display

* Fix the order of 4 main sides in list

* Restore non-toggle behaviour of camera speed

* Fix UI gap between list and tabs

* Force update UI list when player is staged

Hopefully this fixes any issues related to the player appearing in the
list

* Update controls strings

* Fix entity tooltips showing short name

- Also revert changes to common function and just handle in this component

* Include dead in unit switching

* Show rank and vehicle icon in list

- Rank is shown in tooltip
- Vehicle icon is used to see which units in the list are mounted

* Change default vehicle icon

* Show whether medic/engineer in tooltip

* Improve list double click behaviour

* Improve group icon handling

* Use dynamic group icons for drawing

* Fix EFUNC call

* Update all function headers

* All the changes I had staged before arma broke git

Arma managed to crash my whole system again, breaking my git repo and I
resorted to nuking it and pasting the changes I had comitted locally back
in. From memory:

- Fix icon paths
- use distanceSqr for minor speed boost
- Add setting to show map locations in the UI
- Limit location rendering based on distance
- Probably some other crap

* Fix squared comparisons

* Remove unnecessary variable publicity

* Deprecate fnc_stageSpectator

The function was a source of confusion alongside fnc_setSpectator and so
it is replaced by an additional parameter to hide the unit as part of
fnc_setSpectator. No longer is the unit moved either, to reduce complexity
and give more control to mission maker.

* Fix undefined variable

* Update spectator framework doc

* Update spectator feature doc

* Fix typos and grammar

* Revent version introduced number

* Update with new changes
This commit is contained in:
SilentSpike 2017-10-17 19:19:10 +01:00 committed by jonpas
parent b366be0277
commit 51a61653f4
3 changed files with 273 additions and 394 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
addons/spectator/functions/fnc_updateUnits.sqf
View File

@ -7,7 +7,7 @@
* 1: Units to hide in the list <ARRAY>
*
* Return Value:
* None <NIL>
* None
*
* Example:
* [allPlayers, [player]] call ace_spectator_fnc_updateUnits

428
docs/wiki/feature/spectator.md
View File

@ -12,426 +12,68 @@ version:
patch: 0
---
## 1. Overview
## 1. Features
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.
ACE3 spectator is heavily inspired by Bohemia Interactive's [End Game Spectator](https://community.bistudio.com/wiki/EG_Spectator_Mode). The reason for this is to try and keep the spectator user experience relatively consistent and so that ACE3 can focus more on providing additional functionality than reinventing how spectator actually works.
### 1.1 Spectator System
### 1.1 Camera modes
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:
There are 3 available camera modes which can be enabled/disabled via the relevant setting and public API:
- An `"ace_spectator"` [respawn template](https://community.bistudio.com/wiki/Arma_3_Respawn)
- Public functions `ace_spectator_fnc_setSpectator` and `ace_spectator_fnc_stageSpectator`
- Free Camera
- First Person
- Third Person
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.
A button dock at the bottom of the UI can be used to switch camera modes as well as <kbd>Spacebar</kbd>.
An example description.ext file using the respawn template:
### 1.2 Vision modes
```js
respawn = 3;
respawnDelay = 180;
respawnTemplates[] = {"ace_spectator"};
respawnTemplatesWest[] = {"ace_spectator","Counter","Wave"};
```
By default, there are 3 available vision modes which can be enabled/disabled via the relevant setting and public API:
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:
- Normal
- Night Vision
- Thermal (White and Black Hot)
`ace_spectator_fnc_setSpectator`
However, via the public API a range of additional thermal vision modes are also possible. Cycling through available vision modes is currently hard coded to the <kbd>N</kbd> key.
```js
/*
* 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
*/
```
### 1.3 Unit focusing
`ace_spectator_fnc_stageSpectator`
Focusing on a unit changes the active camera view to observe the given unit. In free camera, this means the camera will center on the unit regardless of where you move it (while in 1PP and 3PP the camera behaves as expected). To change the current focus, units can be:
```js
/*
* 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)
* 1: Spectator stage <BOOL> (default: true)
*
* Return Value:
* None <NIL>
*
* Example:
* [player, false] call ace_spectator_fnc_stageSpectator
*/
```
- Clicked on in the 3D world (their rendered name will become highlighted when moused over)
- Clicked on in the 2D map (their icon will become highlighted when moused over)
- Clicked on in the unit list on the left side of the UI
### 1.2 Spectatable Units
Before 1PP and 3PP camera modes can be entered, a unit must be in focus as these camera modes require a unit to observe. To un-focus the free camera, simply click again while no new unit is highlighted.
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:
### 1.4 Spectator map
- Unit filter
- Unit whitelist/blacklist
Pressing the <kbd>M</kbd> key will open the spectator map. All spectatable units and locations are rendered on the map as well as the free camera if active. To teleport the free camera simply click on the map at the desired location (with no unit highlighted).
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:
### 1.5 Camera speeds
- **No units**
- **Player units**
- **Playable units** *(default)*
- **All units**
Unlike End Game Spectator, instead of having two levels of fast camera speed, the default camera speed is more responsive and a hotkey is provided to slow the camera speed (for when more fine movement is desired) as well as increase it (for when traveling distance is desired).
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):
### 1.6 Draw distance
```js
/*
* Arguments:
* 0: Units to add to the whitelist <ARRAY>
* 1: Use blacklist <BOOL> <OPTIONAL>
*
* Return Value:
* None <NIL>
*
* Example:
* [allUnits,true] call ace_spectator_fnc_updateUnits
*
*/
```
Upon opening spectator the view distance defaults to 1200m, the <kbd>Page Up</kbd> and <kbd>Page Down</kbd> keys can be used to incrementally increase and decrease this view distance within the range of 500m to 2500m.
### 1.3 Spectatable Sides
### 1.7 Camera lights
Spectatable sides can be considered another filter for the unit list to determine which units are available to spectate base on their side. As such, units can also be whitelisted from this filter as detailed above. There are two stages in the spectatable sides mechanism:
Pressing the <kbd>L</kbd> hotkey will toggle local camera lights on an off. A light is created at both the cursor position and camera position to assist in viewing night time scenarios without night vision. Nobody else will see these lights since they are created locally.
- Side list
- Side filter
### 1.8 Focus info widget
The side list is a list of sides *possible* to spectate. By default this is always `[west, east, resistance, civilian]` and does not change. To update the local client's side list the function `ace_spectator_fnc_updateSpectatableSides` can be used:
When a unit is focused on, a small widget will be shown in the center of the UI with details on their loadout and performance. To toggle this UI element on and off the <kbd>I</kbd> hotkey can be used.
```js
/*
* Arguments:
* 0: Sides to add <ARRAY>
* 1: Sides to remove <ARRAY>
*
* Return Value:
* Spectatable sides <ARRAY>
*
* Example:
* [[west], [east,civilian]] call ace_spectator_fnc_updateSpectatableSides
*/
```
### 1.9 Unit drawing
The side filter is then applied *on top* of this list to determine which sides are *truly* available to spectate. It's controlled by setting `ace_spectator_filterSides` and there are four possible options:
The <kbd>O</kbd> hotkey can be used to toggle unit and group drawing on and off. Units will be drawn with a caret icon above their heads and their nametag when in close proximity to the camera. Groups will receive a dynamic (approximate) NATO group icon based on their composition - which is rendered above the group leader.
- **Player side** *(default)*
- **Friendly sides**
- **Hostile sides**
- **All sides**
### 1.10 Projectile drawing
### 1.4 Camera Modes
The <kbd>P</kbd> hotkey can be used to toggle projectile drawing on and off. Projectiles originating from units listed in the unit list will be drawn in real time and allow fire fights to be observed more clearly. Note that this feature may have a significant performance impact in scenarios with lots of projectiles on screen at once.
There are 3 possible camera modes:
- **Free**
- **Internal**
- **External**
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:
```js
/*
* Possible camera modes are:
* - 0: Free
* - 1: Internal
* - 2: External
*
* Arguments:
* 0: Camera modes to add <ARRAY>
* 1: Camera modes to remove <ARRAY>
*
* Return Value:
* Available camera modes <ARRAY>
*
* Example:
* [[0], [1,2]] call ace_spectator_fnc_updateCameraModes
*/
```
### 1.5 Vision Modes
Vision modes are only available in free camera mode. By default there are 4 available vision modes:
- **Normal**
- **Night vision**
- **Thermal imaging (white hot)**
- **Thermal imaging (black hot)**
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:
```js
/*
* Possible vision modes are:
* - -2: Normal
* - -1: Night vision
* - 0: White hot
* - 1: Black hot
* - 2: Light Green Hot / Darker Green cold
* - 3: Black Hot / Darker Green cold
* - 4: Light Red Hot / Darker Red Cold
* - 5: Black Hot / Darker Red Cold
* - 6: White Hot / Darker Red Cold
* - 7: Thermal (Shade of Red and Green, Bodies are white)
*
* Arguments:
* 0: Vision modes to add <ARRAY>
* 1: Vision modes to remove <ARRAY>
*
* Return Value:
* Available vision modes <ARRAY>
*
* Example:
* [[0], [1,2]] call ace_spectator_fnc_updateVisionModes
*/
```
### 1.6 Camera Attributes
The spectator camera has 8 manipulatable attributes:
- **Camera mode:** The camera view
- **Camera unit:** The unit used for internal and external view
- **Camera vision:** The vision mode used by the free camera
- **Camera position:** The position of the free camera
- **Camera pan:** The pan (direction/heading) of the free camera
- **Camera tilt:** The tilt (pitch) of the free camera
- **Camera zoom:** The zoom level of the free camera
- **Camera speed:** The movement speed of the free camera
Function `ace_spectator_fnc_setCameraAttributes` can be used to change any of these attributes at any point (including before spectator has ever opened):
```js
/*
* Arguments:
* 0: Camera mode <NUMBER> <OPTIONAL>
* - 0: Free
* - 1: Internal
* - 2: External
* 1: Camera unit (objNull for random) <OBJECT> <OPTIONAL>
* 2: Camera vision <NUMBER> <OPTIONAL>
* - -2: Normal
* - -1: Night vision
* - 0: Thermal white hot
* - 1: Thermal black hot
* 3: Camera position (ATL) <ARRAY> <OPTIONAL>
* 4: Camera pan (0 - 360) <NUMBER> <OPTIONAL>
* 5: Camera tilt (-90 - 90) <NUMBER> <OPTIONAL>
* 6: Camera zoom (0.01 - 2) <NUMBER> <OPTIONAL>
* 7: Camera speed in m/s (0.05 - 10) <NUMBER> <OPTIONAL>
*
* Return Value:
* None <NIL>
*
* Example:
* [1, objNull] call ace_spectator_fnc_setCameraAttributes
*/
```
## 2. Usage
### 2.1 Spectator Shortcuts
Shortcuts are currently hardcoded in the ACE3 spectator system. Future versions are likely to change that.
#### 2.1.1 Interface Shortcuts
<table>
<thead>
<tr>
<th>Shortcut</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td><kbd>1</kbd></td>
<td>Toggle unit list</td>
</tr>
<tr>
<td><kbd>2</kbd></td>
<td>Toggle help</td>
</tr>
<tr>
<td><kbd>3</kbd></td>
<td>Toggle toolbar</td>
</tr>
<tr>
<td><kbd>4</kbd></td>
<td>Toggle compass</td>
</tr>
<tr>
<td><kbd>5</kbd></td>
<td>Toggle unit icons</td>
</tr>
<tr>
<td><kbd>M</kbd></td>
<td>Toggle map</td>
</tr>
<tr>
<td><kbd>Backspace</kbd></td>
<td>Toggle interface</td>
</tr>
</tbody>
</table>
#### 2.1.2 Free Camera Shortcuts
<table>
<thead>
<tr>
<th>Shortcut</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td><kbd>W</kbd></td>
<td>Camera forward</td>
</tr>
<tr>
<td><kbd>S</kbd></td>
<td>Camera backward</td>
</tr>
<tr>
<td><kbd>A</kbd></td>
<td>Camera left</td>
</tr>
<tr>
<td><kbd>D</kbd></td>
<td>Camera right</td>
</tr>
<tr>
<td><kbd>Q</kbd></td>
<td>Camera up</td>
</tr>
<tr>
<td><kbd>Z</kbd></td>
<td>Camera down</td>
</tr>
<tr>
<td><kbd>RMB</kbd></td>
<td>Pan camera</td>
</tr>
<tr>
<td><kbd>LMB</kbd></td>
<td>Dolly camera</td>
</tr>
<tr>
<td><kbd>⇧&nbsp;Shift</kbd></td>
<td>Speed boost</td>
</tr>
<tr>
<td><kbd>F</kbd></td>
<td>Focus on unit</td>
</tr>
</tbody>
</table>
#### 2.1.3 Camera Attribute Shortcuts
<table>
<thead>
<tr>
<th>Shortcut</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td><kbd>Up arrow</kbd></td>
<td>Next camera</td>
</tr>
<tr>
<td><kbd>Down arrow</kbd></td>
<td>Previous camera</td>
</tr>
<tr>
<td><kbd>Right arrow</kbd></td>
<td>Next unit</td>
</tr>
<tr>
<td><kbd>Left arrow</kbd></td>
<td>Previous unit</td>
</tr>
<tr>
<td><kbd>N</kbd></td>
<td>Next vision mode</td>
</tr>
<tr>
<td><kbd>Ctrl</kbd>+<kbd>N</kbd></td>
<td>Previous vision mode</td>
</tr>
<tr>
<td><kbd>Scrollwheel</kbd></td>
<td>Adjust zoom</td>
</tr>
<tr>
<td><kbd>Ctrl</kbd>+<kbd>Scrollwheel</kbd></td>
<td>Adjust speed</td>
</tr>
<tr>
<td><kbd>Num-</kbd>/<kbd>Num+</kbd></td>
<td>Increment zoom</td>
</tr>
<tr>
<td><kbd>Ctrl</kbd>+<kbd>Num-</kbd>/<kbd>Num+</kbd></td>
<td>Increment speed</td>
</tr>
<tr>
<td><kbd>Alt</kbd>+<kbd>Num-</kbd></td>
<td>Reset zoom</td>
</tr>
<tr>
<td><kbd>Alt</kbd>+<kbd>Num+</kbd></td>
<td>Reset speed</td>
</tr>
</tbody>
</table>
### 2.2 The Interface
#### 2.2.1 Unit list
The unit list on the left lists all of the units currently available to spectate.
Double click on any unit name in the list to switch to the unit.
Double click on the current unit to switch between internal and external view.
#### 2.2.2 Toolbar
The toolbar along the bottom of the screen displays various useful values. From left to right these are:
- Unit name
- Camera mode
- Vision mode/Unit side
- 24-hour Clock
- Camera zoom/Unit depth
- Camera/Unit speed
#### 2.2.3 Map
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.
## 3. Dependencies
## 2. Dependencies
{% include dependencies_list.md component="spectator" %}

237
docs/wiki/framework/spectator-framework.md Normal file
View File

@ -0,0 +1,237 @@
---
layout: wiki
title: Spectator Framework
description: Explains how to set-up and manipulate the ACE3 spectator system.
group: framework
parent: wiki
mod: ace
version:
major: 3
minor: 2
patch: 0
---
## 1. Enabling Spectator
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) which can be enabled via description.ext or through the eden editor multiplayer attributes
- The public function `ace_spectator_fnc_setSpectator` which can be used at any time to open/close the spectator interface
With respawn template `ace_spectator` in effect players will enter spectator mode upon death and exit upon respawn (if there is respawn). The template is compatible with all respawn types (except `None`/`0`) and allows you to take advantage of the vanilla framework's flexibility (combining templates, side specific templates, etc.).
<div class="panel callout">
<h5>Note:</h5>
<p>It's worth noting that templates "MenuPosition" and "MenuInventory" are not currently compatible with the "ace_spectator" template.</p>
</div>
An example description.ext file using the respawn template:
```cpp
respawn = 3; // Players respawn at base
respawnDelay = 180; // Players spectate for 3 minutes between respawns
respawnTemplates[] = {"ace_spectator"}; // Enables the spectator template for all
respawnTemplatesWest[] = {"ace_spectator","Counter","Wave"}; // Wave respawns and a countdown for west side
```
## 2. Global Settings
To tweak the default spectator experience three settings are provided:
- **AI Enabled:** Whether AI will appear in the unit list and be spectatable. Defaults to only players.
- **Camera modes:** Which camera modes (1PP, 3PP and Free) are available to use by default.
- **Vision modes:** Which vision modes (Normal, Night and Thermal) are available to use by default.
Note that these settings govern the default spectator behaviour. Through the use of public functions, the spectator experience can be more finely controlled (e.g. to limit each player to only be able to spectate units on their side) on top of these.
## 3. Events
### 3.1 Listenable
Event Name | Passed Parameter(s) | Locality | Description
---------- | ----------- | ------------------- | --------
`ace_spectatorSet` | [_isSpectator, _player] | Global | Player's spectator status was changed
## 4. Scripting
While the majority of scenarios can be set up as desired using only the settings provided, some require more specific limitations on what functionality is available to whom. All of the following public functions are provided to try and accommodate for such needs.
### 4.1 Change the local player's spectator status
`ace_spectator_fnc_setSpectator`
If the interface is not forced then the player can close spectator with the <kbd>ESC</kbd> key.
If the player is hidden they will become invisible, invulnerable and removed from their group until they exit spectator.
```cpp
* Arguments:
* 0: Spectator state of local client <BOOL> (default: true)
* 1: Force interface <BOOL> (default: true)
* 2: Hide player (if alive) <BOOL> (default: true)
*
* Return Value:
* None
*
* Example:
* [true] call ace_spectator_fnc_setSpectator
```
### 4.2 Whitelist/Blacklist units available to spectate
`ace_spectator_fnc_updateUnits`
Whitelisted units will always show in the unit list regardless of the usual filtering applied (with the exception of the local player, who will never be shown). Blacklisted units will always be filtered out of the unit list (this overrides the whitelist).
Note that this function takes local effect, so only the local player will see these changes.
```cpp
* Arguments:
* 0: Units to show in the list <ARRAY>
* 1: Units to hide in the list <ARRAY>
*
* Return Value:
* None
*
* Example:
* [allPlayers, [player]] call ace_spectator_fnc_updateUnits
```
### 4.3 Add/Remove sides available to spectate
`ace_spectator_fnc_updateSides`
By default, units on all 4 sides (`west`, `east`, `independent` and `civilian`) are available to spectate provided they pass through basic filtering (AI setting, simulated and visible). By removing a side, you effectively add a layer of filtering that removes units belonging to that side from the spectator unit list. Adding sides is simply available to reverse a removal - you cannot add a side beyond the main 4 (e.g. `sideLogic`) as those units do not appear in the `allUnits` array (you could whitelist a unit belonging to such a side).
Note that this function takes local effect, so only the local player will see these changes.
```cpp
* Arguments:
* 0: Sides to add <ARRAY>
* 1: Sides to remove <ARRAY>
*
* Return Value:
* Sides available <ARRAY>
*
* Example:
* [[west], [east,civilian]] call ace_spectator_fnc_updateSides
```
### 4.4 Add/Remove available camera modes
`ace_spectator_fnc_updateCameraModes`
You can change the spectator camera modes available at any point during the mission and independently on different machines with this function (e.g. if you only want one side of players to have a free camera). Remember that the **Camera modes** setting will change which modes are available to everyone by default - changes with this function will override that.
Note that this function takes local effect, so only the local player will experience these changes.
```cpp
* Possible camera modes are:
* - 0: Free
* - 1: First person
* - 2: Follow
*
* Arguments:
* 0: Camera modes to add <ARRAY>
* 1: Camera modes to remove <ARRAY>
*
* Return Value:
* Available camera modes <ARRAY>
*
* Example:
* [[0], [1,2]] call ace_spectator_fnc_updateCameraModes
```
### 4.5 Add/Remove available vision modes
`ace_spectator_fnc_updateVisionModes`
You can change the spectator vision modes available at any point during the mission and independently on different machines with this function (e.g. if you only want one side of players to have night vision). Remember that the **Vision modes** setting will change which modes are available to everyone by default (if thermal is enabled via the setting then both black and white hot are available) - changes with this function will override that.
Note that this function takes local effect, so only the local player will experience these changes.
```cpp
* Possible vision modes are:
* - -2: Normal
* - -1: Night vision
* - 0: White hot
* - 1: Black hot
* - 2: Light Green Hot / Darker Green cold
* - 3: Black Hot / Darker Green cold
* - 4: Light Red Hot / Darker Red Cold
* - 5: Black Hot / Darker Red Cold
* - 6: White Hot / Darker Red Cold
* - 7: Thermal (Shade of Red and Green, Bodies are white)
*
* Arguments:
* 0: Vision modes to add <ARRAY>
* 1: Vision modes to remove <ARRAY>
*
* Return Value:
* Available vision modes <ARRAY>
*
* Example:
* [[0], [1,2]] call ace_spectator_fnc_updateVisionModes
```
### 4.6 Set the camera mode/focus/vision/position/direction
`ace_spectator_fnc_setCameraAttributes`
You can change any of the listed camera attributes at any time during a mission (including before spectator has opened if you want to pre-set them to change the initial view). All arguments are optional and default to no change (if you use `nil`).
Note that this function takes local effect, so only the local player will experience these changes.
```cpp
* Arguments:
* 0: Camera mode <NUMBER>
* - 0: Free
* - 1: First Person
* - 2: Follow
* 1: Camera focus <OBJECT or BOOL>
* 2: Camera vision <NUMBER>
* - -2: Normal
* - -1: Night vision
* - 0: Thermal white hot
* - 1: Thermal black hot
* - ...
* 3: Camera position (ATL) <ARRAY>
* 4: Camera direction (0 - 360) <NUMBER>
*
* Notes:
* - If camera mode is not free and camera has no focus, random will be used
* - To remove any current camera focus in free cam, use objNull
* - To select a random camera focus, use a boolean
*
* Return Value:
* None
*
* Example:
* [1, objNull] call ace_spectator_fnc_setCameraAttributes
```
### 4.7 Get the camera mode/focus/vision/position/direction
`ace_spectator_fnc_getCameraAttributes`
Returns an array of the listed camera attributes (see `setCameraAttributes` for more details) for the local player. If the spectator camera is not currently active any pre-set attributes will be returned (otherwise default values will be returned - position will be `[0,0,0]` if unset).
```cpp
* Arguments:
* None
*
* Return Value:
* [Mode, Focus, Vision, Position, Direction] <ARRAY>
*
* Example:
* [] call ace_spectator_fnc_getCameraAttributes
```
### 4.8 Get all players currently spectating
`ace_spectator_fnc_players`
Will return both alive and dead players (note that dead player corpses are never deleted until the player has respawned - even when `deleteVehicle` is used on them).
```cpp
* Arguments:
* None
*
* Return Value:
* Spectator Players <ARRAY>
*
* Example:
* [] call ace_spectator_fnc_players
```