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

Merge pull request #1918 from acemod/spect-doc

Browse Source 
ace_spectator documentation
This commit is contained in:
SilentSpike 2015-07-27 15:57:48 +01:00
commit 00684ccb64
2 changed files with 416 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

356
documentation/feature/spectator.md Normal file
View File

@ -0,0 +1,356 @@
---
layout: wiki
title: Spectator
description: A flexible spectator system
group: feature
parent: wiki
---
## 1. Overview
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.
### 1.1 Spectator System
The current iteration of the ACE3 spectator system only officially supports scenarios using [respawn type](https://community.bistudio.com/wiki/Arma_3_Respawn#Respawn_Types) 3 (or "BASE"). However there's nothing to stop its use alongside anything else, just be aware that it might not function entirely as expected.
By default, the ACE3 spectator system does nothing - meaning existing missions will behave exactly as before. The setting `ace_spectator_onDeath` can be used to automatically put players into spectator mode each time they die.
For mission makers who seek a more advanced setup (such as multiple lives or wave respawning) the function `ace_spectator_fnc_setSpectator` is provided to transition players to/from spectator mode as desired:
```
* Arguments:
* 0: Unit to put into spectator state <OBJECT>
* 1: New spectator state <BOOL> <OPTIONAL>
*
* Return Value:
* None <NIL>
*
* Example:
* [player, true] call ace_spectator_fnc_setSpectator
```
### 1.2 Spectatable Units
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:
- Unit filter
- Unit whitelist/blacklist
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 three possible options:
- **No units**
- **Player units** *(default)*
- **All units**
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):
```
* 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
*
```
### 1.3 Spectatable Sides
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:
- Side filter
- Side list
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.
Note that the unit whitelist/blacklist also serves to override this side filtering mechanism.
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:
```
* 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
```
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:
- **Player side** *(default)*
- **Friendly sides**
- **Hostile sides**
- **All sides**
### 1.4 Camera Modes
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:
```
* 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:
```
* 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 ay point (including before spectator has ever opened):
```
* 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>H</kbd></td>
<td>Toggle help</td>
</tr>
<tr>
<td><kbd>M</kbd></td>
<td>Toggle map</td>
</tr>
<tr>
<td><kbd>1</kbd></td>
<td>Toggle unit list</td>
</tr>
<tr>
<td><kbd>2</kbd></td>
<td>Toggle toolbar</td>
</tr>
<tr>
<td><kbd>3</kbd></td>
<td>Toggle compass</td>
</tr>
<tr>
<td><kbd>4</kbd></td>
<td>Toggle unit icons</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>LMB</kbd></td>
<td>Camera dolly</td>
</tr>
<tr>
<td><kbd>RMB</kbd></td>
<td>Camera pan and tilt</td>
</tr>
<tr>
<td><kbd>Scrollwheel</kbd></td>
<td>Zoom +/-</td>
</tr>
<tr>
<td><kbd>Ctrl</kbd>+<kbd>Scrollwheel</kbd></td>
<td>Speed +/-</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>
</tbody>
</table>
#### 2.1.3 Unit Camera Shortcuts
<table>
<thead>
<tr>
<th>Shortcut</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<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>RMB</kbd></td>
<td>Toggle gun camera</td>
</tr>
</tbody>
</table>
#### 2.1.4 General 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>
</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
- Camera zoom/Unit side
- 24-hour Clock
- Vision mode/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. The unit icons are tied into the unit icon toggle shortcut. When spectating a unit the map will also show the icons of units it knows about. In free camera you can double click on the map to teleport the camera to the position of the mouse.
## 3. Dependencies
`ace_common`

90
documentation/missionmaker/modules.md
View File

@ -114,8 +114,8 @@ Check all addons instead of only those of ACE3?<br>
`Default value: "No"` `Default value: "No"`
3. **Whitelist**<br> 3. **Whitelist**<br>
You can make a whitelist of addons that don't have to be on the server. If you want to use the "Check all addons" option of this module and allow the usage of client side modifications like Blastcore or JSRS, you have to list them here. You can make a whitelist of addons that don't have to be on the server. If you want to use the "Check all addons" option of this module and allow the usage of client side modifications like Blastcore or JSRS, you have to list them here.
The list must be in the following format: `["ADDON1","ADDON2",...]` where the addons are CfgPatches references to all PBOs of the optional mod. To figure these out, you can use the scripting command `activatedAddons` in the editor while those mods are enabled. The list must be in the following format: `["ADDON1","ADDON2",...]` where the addons are CfgPatches references to all PBOs of the optional mod. To figure these out, you can use the scripting command `activatedAddons` in the editor while those mods are enabled.
Example 1: @Blastcore-A3:<br> Example 1: @Blastcore-A3:<br>
``` ```
@ -181,13 +181,13 @@ Should players be allowed to use the Team Management Menu?.<br>
### 1.10 Make Unit Surrender ### 1.10 Make Unit Surrender
*Part of: ace_captives* *Part of: ace_captives*
Syncing units to that module sets them in the captive state with their arms behind their back. Usefull for e.g. hostage rescue missions. Syncing units to that module sets them in the captive state with their arms behind their back. Usefull for e.g. hostage rescue missions.
### 1.11 Map ### 1.11 Map
*Part of: ace_map* *Part of: ace_map*
ACE3 introdcues a bit more realism for the vanilla Arma 3 map and how it behaves. Some of these settings can be toggled by this module. ACE3 introdcues a bit more realism for the vanilla Arma 3 map and how it behaves. Some of these settings can be toggled by this module.
**Settings:** **Settings:**
@ -223,8 +223,8 @@ How much map data is filled on MicroDAGR's.<br>
### 1.13 MK6 Settings ### 1.13 MK6 Settings
*Part of: ace_mk6mortar* *Part of: ace_mk6mortar*
ACE3 now includes the first iteration of getting a less arcady point and click mortar experience. ACE3 now includes the first iteration of getting a less arcady point and click mortar experience.
Placing this modules allows you to enable the increased realism in game. Placing this modules allows you to enable the increased realism in game.
**Settings:** **Settings:**
@ -292,11 +292,41 @@ The "Respawn System" module enables players to respawn with the gear they had be
Respawn with the gear a player had just before his death.<br> Respawn with the gear a player had just before his death.<br>
`Default value: No` `Default value: No`
### 1.17 Spectator Settings
*Part of: ace_spectator*
### 1.17 SwitchUnits System Configure how the spectator system will operate by default.
**Settings:**
1. **Spectate on death (Boolean)**<br>
Enables spectator upon death.<br>
`Default value: No`
2. **Unit filter (Option)**<br>
Method of filtering spectatable units.<br>
`Default value: "Only players"`
3. **Side filter (Option)**<br>
Method of filtering spectatable sides.<br>
`Default value: "Player side"`
4. **Camera modes (Option)**<br>
Camera modes that can be used.<br>
`Default value: "All"`
5. **Vision modes (Option)**<br>
Vision modes that can be used.<br>
`Default value: "All"`
6. **Unit icons (Boolean)**<br>
Render icons above spectatable units.<br>
`Default value: Yes`
### 1.18 SwitchUnits System
*Part of: ace_switchunits* *Part of: ace_switchunits*
The [SwitchUnits System](./mission-tools.html#2.-ace-switchunits) enables players to control certain AI units on the map. The [SwitchUnits System](./mission-tools.html#2.-ace-switchunits) enables players to control certain AI units on the map.
**Settings:** **Settings:**
@ -325,16 +355,16 @@ The safe zone around players from a different team (in meters)<br>
`Default value: 200` `Default value: 200`
### 1.18 Vehicle Lock ### 1.19 Vehicle Lock
*Part of: ace_vehiclelock* *Part of: ace_vehiclelock*
These modules allow you to lock and unlock vehicles and their inventory using a key. Players don't receive a key automatically; for key names, see [Classnames Wiki](http://ace3mod.com/wiki/missionmaker/classnames.html#vehicle-lock). These modules allow you to lock and unlock vehicles and their inventory using a key. Players don't receive a key automatically; for key names, see [Classnames Wiki](http://ace3mod.com/wiki/missionmaker/classnames.html#vehicle-lock).
#### 1.18.1 Vehicle Key Assign #### 1.19.1 Vehicle Key Assign
Sync with vehicles and players. Will handout custom keys to players for every synced vehicle. Only valid for objects present at mission start. Sync with vehicles and players. Will handout custom keys to players for every synced vehicle. Only valid for objects present at mission start.
Example: `[bob, car1, true] call ACE_VehicleLock_fnc_addKeyForVehicle;` - will add a key to bob and program it to work only on car1 Example: `[bob, car1, true] call ACE_VehicleLock_fnc_addKeyForVehicle;` - will add a key to bob and program it to work only on car1
#### 1.18.2.1 Vehicle Lock Setup #### 1.19.2.1 Vehicle Lock Setup
Settings for lockpick strength and initial vehicle lock state. Removes ambiguous lock states. Settings for lockpick strength and initial vehicle lock state. Removes ambiguous lock states.
**Settings:** **Settings:**
@ -351,12 +381,12 @@ Set lock state for all vehicles (removes ambiguous lock states)<br>
Default Time to lockpick (in seconds)<br> Default Time to lockpick (in seconds)<br>
`Default value: 10` `Default value: 10`
#### 1.18.2.2 Vehicle setVariables #### 1.19.2.2 Vehicle setVariables
* `ACE_VehicleLock_lockSide` - SIDE: overrides a vehicle's side, allowing locking and unlocking using a different side's key. For example: Unlocking INDEP vehicles with a BLUFOR key. * `ACE_VehicleLock_lockSide` - SIDE: overrides a vehicle's side, allowing locking and unlocking using a different side's key. For example: Unlocking INDEP vehicles with a BLUFOR key.
* `ACE_vehicleLock_lockpickStrength` - NUMBER: seconds, determines how long lockpicking with take, overrides the value set in the module for a specific vehicle of the mission maker's choice. * `ACE_vehicleLock_lockpickStrength` - NUMBER: seconds, determines how long lockpicking with take, overrides the value set in the module for a specific vehicle of the mission maker's choice.
### 1.19 View Distance Limiter ### 1.20 View Distance Limiter
*Part of: ace_viewdistance* *Part of: ace_viewdistance*
This module allows disabling the ACE3 View Distance feature as well as setting a view distance limit. This module allows disabling the ACE3 View Distance feature as well as setting a view distance limit.
@ -372,7 +402,7 @@ Sets the limit for how high clients can raise their view distance (<= 10000)
`Default value: 10000` `Default value: 10000`
### 1.20 Weather ### 1.21 Weather
*Part of: ace_weather* *Part of: ace_weather*
This module allows you to customize the weather settings. This module allows you to customize the weather settings.
@ -415,9 +445,9 @@ Synchronizes lightnings, rainbow, fog, ...<br>
6. **Update Interval (Number)**<br> 6. **Update Interval (Number)**<br>
Defines the interval (seconds) between weather updates.<br> Defines the interval (seconds) between weather updates.<br>
`Default value: 60` `Default value: 60`
### 1.21 Wind Deflection
### 1.22 Wind Deflection
*Part of: ace_winddeflection* *Part of: ace_winddeflection*
This module allows you to define when wind deflection is active. This module allows you to define when wind deflection is active.
@ -450,32 +480,32 @@ Defines the interval between every calculation step.<br>
Defines the radius around the player (in meters) at which projectiles are wind deflected.<br> Defines the radius around the player (in meters) at which projectiles are wind deflected.<br>
`Default value: 3000` `Default value: 3000`
### 1.22 Zeus Settings ### 1.23 Zeus Settings
*part of: ace_zeus* *part of: ace_zeus*
This module provides control over vanilla aspects of Zeus. This module provides control over vanilla aspects of Zeus.
**Settings:** **Settings:**
1. **Ascension Messages (Option)**<br> 1. **Ascension Messages (Boolean)**<br>
Display global popup messages when a player is assigned as Zeus<br> Display global popup messages when a player is assigned as Zeus.<br>
`Default value: No` `Default value: No`
2. **Zeus Eagle (Boolean)**<br> 2. **Zeus Eagle (Boolean)**<br>
Spawn an eagle that follows the Zeus camera<br> Spawn an eagle that follows the Zeus camera.<br>
`Default value: No` `Default value: No`
3. **Wind Sounds (Boolean)**<br> 3. **Wind Sounds (Boolean)**<br>
Play wind sounds when Zeus remote controls a unit<br> Play wind sounds when Zeus remote controls a unit.<br>
`Default value: No` `Default value: No`
4. **Ordnance Warning (Boolean)**<br> 4. **Ordnance Warning (Boolean)**<br>
Play a radio warning when Zeus uses ordnance<br> Play a radio warning when Zeus uses ordnance.<br>
`Default value: No` `Default value: No`
5. **Reveal Mines (Scalar)**<br> 5. **Reveal Mines (Option)**<br>
Reveal mines to allies and/or place map markers<br> Reveal mines to allies and place map markers.<br>
`Default value: Disabled` `Default value: "Disabled"`
### 1.23 LSD Vehicles ### 1.23 LSD Vehicles
*Part of: ace_core* *Part of: ace_core*
@ -599,7 +629,7 @@ Pain is only temporarly supressed not removed.
### 2.3 Revive Settings ### 2.3 Revive Settings
This modules allows a mission maker to limit the amount of revives for units in basic and advanced medical. This modules allows a mission maker to limit the amount of revives for units in basic and advanced medical.
**Settings:** **Settings:**
@ -618,7 +648,7 @@ Max amount of lives a unit. 0 or -1 is disabled.<br>
### 2.4 Set Medic Class ### 2.4 Set Medic Class
Using this module you can define which unit class is defined as a medic / doctor. Using this module you can define which unit class is defined as a medic / doctor.
**Settings:** **Settings:**
@ -662,7 +692,7 @@ Whether or not the objects in the list will be a medical vehicle.<br>
### 3.1 Ambiance Sounds ### 3.1 Ambiance Sounds
Used for ambiance sounds loop (synced across MP). Used for ambiance sounds loop (synced across MP).
This module randomizes the time when the sound file is played and the position where the sound file is played (If "Follow Players" is set to No). This module randomizes the time when the sound file is played and the position where the sound file is played (If "Follow Players" is set to No).
`Minimal Distance` and `Maximal Distance` influence the position from where the sound file is played. Setting both values to 0 forces the module to play the sound from where it was placed in the editor. `Minimal Distance` and `Maximal Distance` influence the position from where the sound file is played. Setting both values to 0 forces the module to play the sound from where it was placed in the editor.
@ -696,4 +726,4 @@ Follow players. If set to false, loop will play sounds only nearby logic positio
7. **Volume (Number)**<br> 7. **Volume (Number)**<br>
The volume of the sounds played<br> The volume of the sounds played<br>
`Default value: 1` `Default value: 1`