diff --git a/addons/spectator/functions/fnc_updateUnits.sqf b/addons/spectator/functions/fnc_updateUnits.sqf index 31bde1ac19..6df7cad8ad 100644 --- a/addons/spectator/functions/fnc_updateUnits.sqf +++ b/addons/spectator/functions/fnc_updateUnits.sqf @@ -7,7 +7,7 @@ * 1: Units to hide in the list * * Return Value: - * None + * None * * Example: * [allPlayers, [player]] call ace_spectator_fnc_updateUnits diff --git a/docs/wiki/feature/spectator.md b/docs/wiki/feature/spectator.md index ab3550650c..cfc3cce0fa 100644 --- a/docs/wiki/feature/spectator.md +++ b/docs/wiki/feature/spectator.md @@ -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 Spacebar. -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 N 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 (default: true) -* -* Return Value: -* None -* -* 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 (default: player) -* 1: Spectator stage (default: true) -* -* Return Value: -* None -* -* 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 M 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 - * 1: Use blacklist - * - * Return Value: - * None - * - * Example: - * [allUnits,true] call ace_spectator_fnc_updateUnits - * - */ -``` +Upon opening spectator the view distance defaults to 1200m, the Page Up and Page Down 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 L 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 I hotkey can be used. -```js -/* - * Arguments: - * 0: Sides to add - * 1: Sides to remove - * - * Return Value: - * Spectatable sides - * - * 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 O 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 P 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 - * 1: Camera modes to remove - * - * Return Value: - * Available camera modes - * - * 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 - * 1: Vision modes to remove - * - * Return Value: - * Available vision modes - * - * 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 - * - 0: Free - * - 1: Internal - * - 2: External - * 1: Camera unit (objNull for random) - * 2: Camera vision - * - -2: Normal - * - -1: Night vision - * - 0: Thermal white hot - * - 1: Thermal black hot - * 3: Camera position (ATL) - * 4: Camera pan (0 - 360) - * 5: Camera tilt (-90 - 90) - * 6: Camera zoom (0.01 - 2) - * 7: Camera speed in m/s (0.05 - 10) - * - * Return Value: - * None - * - * 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 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ShortcutAction
1Toggle unit list
2Toggle help
3Toggle toolbar
4Toggle compass
5Toggle unit icons
MToggle map
BackspaceToggle interface
- -#### 2.1.2 Free Camera Shortcuts - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ShortcutAction
WCamera forward
SCamera backward
ACamera left
DCamera right
QCamera up
ZCamera down
RMBPan camera
LMBDolly camera
⇧ ShiftSpeed boost
FFocus on unit
- -#### 2.1.3 Camera Attribute Shortcuts - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ShortcutAction
Up arrowNext camera
Down arrowPrevious camera
Right arrowNext unit
Left arrowPrevious unit
NNext vision mode
Ctrl+NPrevious vision mode
ScrollwheelAdjust zoom
Ctrl+ScrollwheelAdjust speed
Num-/Num+Increment zoom
Ctrl+Num-/Num+Increment speed
Alt+Num-Reset zoom
Alt+Num+Reset speed
- -### 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" %} diff --git a/docs/wiki/framework/spectator-framework.md b/docs/wiki/framework/spectator-framework.md new file mode 100644 index 0000000000..36c2d628f6 --- /dev/null +++ b/docs/wiki/framework/spectator-framework.md @@ -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.). + +
+
Note:
+

It's worth noting that templates "MenuPosition" and "MenuInventory" are not currently compatible with the "ace_spectator" template.

+
+ +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 ESC 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 (default: true) + * 1: Force interface (default: true) + * 2: Hide player (if alive) (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 + * 1: Units to hide in the list + * + * 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 + * 1: Sides to remove + * + * Return Value: + * Sides available + * + * 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 + * 1: Camera modes to remove + * + * Return Value: + * Available camera modes + * + * 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 + * 1: Vision modes to remove + * + * Return Value: + * Available vision modes + * + * 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 + * - 0: Free + * - 1: First Person + * - 2: Follow + * 1: Camera focus + * 2: Camera vision + * - -2: Normal + * - -1: Night vision + * - 0: Thermal white hot + * - 1: Thermal black hot + * - ... + * 3: Camera position (ATL) + * 4: Camera direction (0 - 360) + * + * 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] + * + * 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 + * + * Example: + * [] call ace_spectator_fnc_players + ```