2022-11-22T20:11:20Z

Dragofer: Removed Setting the Scene as it was released

2022-11-11T10:13:01Z

Dragofer: Created page with "==Audiograph== This article documents the audiograph, which will be available from 2.11 onwards. You can download it from here if you want to use it before 2.11 is released: https://forums.thedarkmod.com/index.php?/topic/20475-dragofers-scripting/ The audiograph is an Inventor's Guild device for playing back recordings stored on spindles. It offers the following features: * Every audiograph can load and unload any spindle, a metal cylin..."

Mission Database

2022-08-07T18:05:49Z

Dragofer: Added concrete steps to the procedure for using pk4diff

All released missions are stored in FM database, which defines what is available in mission downloader in-game.

= Requirements =

In order for a mission to be included in the database, it must satisfy the following conditions:
# It has gone through [[Your Mission - From Beta Testing to Release and Beyond|beta-testing]] by several forum members who did not take part in its creation.
#* As a rare exceptional case, a mission can be rejected from the database if the majority of beta-testers come to conclusion that it is unplayable or its quality is way too low.
# Does not contain any questionable material, potential intellectual property infridgements. Including:
#* using names from the original Thief games
#* using assets from other games
#* having content which is so bad that it is forbidden even on our forums (TODO: link to forum rules?)

A very few missions are installed along with the game, like Saint Lucia or Training Mission.
These official missions are considered to be part of the game, and are '''not''' included in the database.

= SVN =

Starting from 2021, the FM database is stored in SVN repository ([https://bugs.thedarkmod.com/view.php?id=5551 #5551]).
Only TDM team members have access to this SVN.

Here is the SVN address:
:: https://svn.thedarkmod.com/project/missions/trunk

'''But please don't rush to checkout the whole repo yet!'''

=== Checkout everything ===

Yes, you can simply copy the link above to SVN Checkout and get single working copy with all the FMs. But keep in mind that you will have to download ~10 GB of data and the working copy will take ~20 GB of space. In most cases you don't need everything in order to work with the database.

The typical reasons to checkout the whole repo are:
* You want to run automated search or tests over all released FMs.
* You are regular committer of the FM database, added a lot of new missions and updates, so the investment is worth it.

[[File:TortoiseSVN RepoBrowser.png|thumb|TortoiseSVN Repo-browser]]
[[File:FmDatabase_RepoBrowser.png|thumb|Accountant 2 FM in SVN]]

=== Checkout as needed ===

Instead of checking out the whole repo, you can checkout only the few FMs you are going to modify.
This is the recommended approach.

With this approach, you need the Repo-browser feature of TortoiseSVN.
It allows to look through all the directories and files on remote SVN without checking it out first.

The directory structure of SVN is show on the picture.
Most importantly, all information about FM with internal name "qwerty" is stored in <tt>fms/qwerty</tt> subdirectory of the repo.
You can checkout only this directory in order to work with FM, just put this checkout address:

:: https://svn.thedarkmod.com/project/missions/trunk/fms/qwerty

Or find the FM directory in Repo-browser, right-click and select Checkout.

Detailed instructions in the rest of the article assume this approach.

= Add New Mission =

[[File:FmDatabase_AddDirectory.png|thumb|x100px|Add FM directory in Repo-browser]]
[[File:FmDatabase_FmCheckout.png|thumb|x80px|Checkout FM]]
[[File:FmDatabase_Commit2.png|thumb|x70px|Commit changes in FM directory]]
[[File:FmDatabase_CommitAddFiles.png|x120px|thumb|Add new files in Commit dialog]]
[[File:FmDatabase_PrecommitHookFailed.png|x120px|thumb|Precommit hook failed due to wrong value of "type"]]

Before adding new FM, negotiate internal name with FM author.
It must be different from names of all existing FMs, consist of only lowercase letters and digits, be rather short (aim for 10-20 letters).
Among many words in the mission title, prefer rare words and proper nouns over common words when composing the internal name.

Open SVN in Repo-browser, find </tt>fms</tt> directory which contains all the FMs.
Right-click on it and choose Add folder in the context menu.
Then enter the internal name of FM as the name of the new directory and proceed with commit.
Now that the directory has been created, you can checkout it: find the directory in Repo-browser, right-click it and Checkout.

The second step is to upload pk4 files.
Copy all the pk4 files of FM into the working copy directory (i.e. checkout directory).
Open the directory in Windows Explorer, right-click and select SVN commit.
Select all pk4 files with Shift, right-click and select Add.
Also set checkboxes for these files.
Write commit message in the text area above: it should start with internal name of FM in brackets.
When everything is done, hit OK to do the actual commit.

While the pk4 files are already in the repository, they are not yet visible in the database.
A mission is only added when its directory contains <tt>fminfo.xml</tt> file, so now you need to add it.
You can take this file from another FM (find it in Repo-browser, right-click, Open with, select text editor), and adjust it for the FM being added.
Here is explanation for some fields:
* '''internalName''' defines name of the directory and pk4 file.
* '''title''' is the name seen by players in-game.
* '''author''' is one or several people who made the mission.
* '''releaseDate''' shows when the very first version of the mission was added.
* '''type''' is <tt>multi</tt> if mission contains several playable .map files (i.e. is campaign), and <tt>single</tt> otherwise.
* '''size''' is size of the main pk4 file in megabytes displayed to users.
* '''version''' is natural number used by in-game downloader to decide whether update is available or not. Starts with 1.
* '''description''' contains text displayed in in-game downloader when player inspects mission details.
* '''mainPack''' points to the main pk4 file of the mission. Note that the name of file is fully determined by internal name.
* '''localisationPack''' points to _l10n.pk4 file if it exists.

Note that XML cannot directly contain some characters, thus they must be escaped:
* Ampersand (<tt>&amp;</tt>) quotes (<tt>&quot;</tt> or <tt>&apos;</tt>) and angle brackets (<tt>&lt;</tt> or <tt>&gt;</tt>): [https://stackoverflow.com/questions/1091945/what-characters-do-i-need-to-escape-in-xml-documents reference]
* Line break symbol can be inserted as <tt>&#10;</tt> according to [https://stackoverflow.com/questions/2004386/how-to-save-newlines-in-xml-attribute reference]

When you have created <tt>fminfo.xml</tt> file, double-check that all properties are correct.
Then use SVN to add and commit the file, just like you did with pk4 file.

If you did something wrong (most likely), then you will see an error saying that "Commit blocked by pre-commit hook".
A long stacktrace from Python script is included, and the meaningful message should be at the end of it.
Typically, it is either XML validation error saying that something in fminfo.xml is wrong, or a message from some custom failed check.
You need to fix the errors and try to commit again --- until you manage to commit successfully.

As the last step, create subdirectory named <tt>screenshots</tt> in the working copy directory.
Put screenshots in .jpg or .png format into the directory: they will be displayed in in-game mission downloader.
Then add and commit all the screenshot files into the repository, same way as you did for pk4 and xml files.

= Update Mission =

This section covers the case if mission has already been released, but new version should be uploaded.

First of all, make sure you have up-to-date working copy of the FM directory.
If you already have working copy, do right-click and SVN Update in it in Windows Explorer.
If you don't have it yet, then open Repo-browser, find the directory named by FM's internal name, right-click and select Checkout.
If you don't know the internal name, you can learn it like this: install the FM in the game, then look what is written in the <tt>currentfm.txt</tt> file.
Suppose internal name is "qwerty".

There are two ways to update the FM:
# Minor update changes one or several lines in some file, e.g. in .map file or in .gui file. Such update is usually done when TDM engine is changed, FM gets broken, and merely a small spawnarg change is enough to return proper behavior. Usually such changes are done by TDM developers with approval of FM authors.
# Major update covers everything else. It happens when FM author sends a new version of pk4 file, with arbitrary changes in .map file, and probably some other changes.

When doing minor update, prefer editing existing pk4 archive instead of creating a new one from scratch.
For instance, you can open the archive in 7-zip, extract only one file which you want to modify, change it in text editor, then add it back to the archive in 7-zip (overwriting the old version).
It is a '''bad''' idea to extract everything, do some changes, then create a brand new pk4 archive.

Regardless of how major the update is, keep in mind SVN storage specifics to avoid rapid growth of server storage requirements.
Unless full size of FM package is smaller than 100 MB, please run the diff optimization tool. The tool is located in <tt>devel\pk4diff\bin</tt> in the assets SVN repo and requires Python 3. The tool will check how much data is really changed inside the archive. If the changes account for less than 10% of the full package size, then the tool will repack it to ensure that this update takes only a very little additional space on server. See more details in [[#Storage Concerns]] section.

The procedure (for Windows) is as follows:

# replace the .pk4 in your working copy of the mission database with your modified .pk4
# if you haven't done so already, install Python 3 and make sure during the installation that it's added as an environment variable
# copy&paste pk4diff.py, pk4diffexe.exe and xdelta3.exe from <tt>darkmod_svn\devel\pk4diff\bin</tt> to the FM's mission database folder next to the .pk4
# open the Windows command console
# type cd into the console, then copy-paste in the path of the FM's SVN folder and hit enter to switch to this folder. Use "cd /d" instead of "cd" if this is a different drive than the one currently mentioned in the console. For exampple: cd D:\games\darkmod_fms\packed\fms\cleanneighbourhood
# paste this command into the command console, adjusting the name of the .pk4: py pk4diff.py --optimize cleanneighbourhood.pk4
# load the .pk4 in TDM to test that it works, then commit it

Now you need to edit <tt>fminfo.xml</tt> file:
# Increment the integer in "version" property by one. Otherwise in-game downloader won't know that the mission has been updated.
# Probably update "size" property if it has changed significantly.

After you have dealt both with pk4 storage concerns and with XML file update, it's time to commit the changes.
Open working copy directory in Windows Explorer, right-click and select SVN Commit.
You should see at least two files marked as modified with checkboxes set: <tt>qwerty.pk4</tt> and <tt>fminfo.xml</tt>.
Write commit message which describes the changes. Start commit message with FM internal name in brackets.
If the new version came from the author, write something like "New version: sent to me by XyMegaMapper yesterday".
If the update did not come from FM author, then all the changes must be described in full detail!
In case of minor update, it can be something like "In guis/mainmenu_custom_defs.gui, removed MM_BRIEFING_VIDEO_MATERIAL_K defines for K > 1".
Finally, click OK to commit the changes.

= Storage Concerns =

We store all missions in SVN repository, thus every version of every FM is saved forever.
While total size of all FMs can be 10 GB, the SVN repository can be larger due to storing full history, especially if large FMs are updated many times.
As of 2021, it is not clear yet how bad things will become.
Most likely the repo won't grow too large, but it's better to be careful.
In order to decide how to make history smaller, we should first understand how is SVN repository stored on the server.

=== Xdelta and Zip Format ===

SVN history is a series of revisions.
For every revision, SVN stores the diff between the previous version and the new one for every modified file.
So when we commit an update to pk4 file, the size of SVN repository grows by the size of the diff on pk4 file.
In the worst case the diff can be as large as the new version of pk4 file.
Unfortunately, such worst-case outcome easily happen even if only a few files inside archive were modified.

Pk4 file is an ordinary zip archive, so it is stored in [https://en.wikipedia.org/wiki/ZIP_(file_format)#Structure Zip format]. All files are stored sequentally inside the archive file, one after another.
Every file inside zip archive is compressed independently of all the other files, and occupies some subsegment of the file.
If some file was not changed and was not recompressed, then the new archive contains exactly the same bytes for this file as the old archive.
In theory, a perfect diff algorithm can detect it, and avoid including any data for such "not-changed" files into the diff.

In SVN, diff between revisions is computed using xdelta algorithm with search window limited to 100 KB.
Due to the very limited search window, the algorithm cannot reliably detect that files inside the old archive are reused in the new one.
Changing the order of files inside zip archive or removing files larger than 100 KB are enough to completely break the diff algorithm, resulting in a maximum-size diff.
That's why even using 7-zip to modify the old archive does not guarantee that your commit will produce small diff.
In fact, maximum-size diff is almost guaranteed if you remove at least one file of size larger than 100 KB (same can also happen for file modification).

=== Pk4diff Optimization ===

We have a special tool for "optimizing" pk4 file to reduce diff size.
This tool inspects the old and the new versions of the archive and finds which files have equal contents.
Then it repacks the archive in the following way:
# Take old version of the archive.
# Rename all files which were modified or removed to <tt>__trash__/trashN._tbin</tt>.
# Append files which were added or modified to the end of the archive.
The resulting pk4 archive as almost exactly the same as the old one, with new data appended at the end.
It is almost certain that SVN will produce diff file which only contains the differences (the appended data).
The downside is: "optimized" pk4 file is slightly larger because it still stores the old data as "trash".

In order to run the optimizer script, Python 3 must be installed.
Of course, SVN must be available in command line (for TortoiseSVN, make sure to [https://stackoverflow.com/a/9874961/556899 check "command line client tools" during installation]).
The tool is located in <tt>devel/pk4diff/bin</tt> in the assets repo and consists of Python script, pk4diff executable, and xdelta3 executable.
The easiest way to run it is to copy all three files into the directory with pk4 file (which must be in SVN working copy), then execute in command line:

python pk4diff.py --optimize qwerty.pk4

Here is the sample output:

CMD: svn export hhta.pk4@BASE __tmp_clean__.pk4
A __tmp_clean__.pk4
Export complete.
CMD: pk4diffexe __tmp_clean__.pk4 hhta.pk4
Added size: 6676263
Removed size: 33085296
CMD: xdelta3 -e -f -B 524288 -W 524288 -s __tmp_clean__.pk4 hhta.pk4 __tmp_diff__.bin
Xdelta diff size: '''517134007'''
CMD: pk4diffexe __tmp_clean__.pk4 hhta.pk4 __tmp_optimized__.pk4
Added size: 6676263
Removed size: 33085296
CMD: xdelta3 -e -f -B 524288 -W 524288 -s __tmp_clean__.pk4 __tmp_optimized__.pk4 __tmp_diff__.bin
Xdelta diff size: '''6712187'''
Added portion of dead data: '''5.885588%'''
Replacing pk4 file with optimized file

All lines starting with "<tt>CMD:</tt>" shows running some program with some parameters.
The script works like this:
# The procedure starts with exporting clean version of hhta.pk4 using SVN command.
# Then pk4diffexe is run: it displays how many bytes are added/removed in the update. The full FM package is about 500 MB, so the changes are pretty small in this example.
# xdelta3 is run to estimate initial size of the diff. Obviously, it is maximum-size diff in this example (+ 500 MB to repo size).
# pk4diffexe is run again, but now it produces an optimized pk4 file.
# xdelta3 is run again on the optimized pk4 file. The diff size becomes about 6 MB, so the optimization has reduced diff a lot.
# The optimized pk4 file contains some trash data, and we are told which portion of the optimized pk4 is trash. It's only 6% in this case (33 MB).
# Since portion of trash is lower than 10%, the pk4 file is replaced with the optimized one. If there is too much trash, then optimized pk4 is simply deleted with a different message.

After running the program, the <tt>hhta.pk4</tt> file is modified: now it is the optimized version. Also, there is file <tt>hhta.pk4.old</tt> nearby: this is the copy of modified pk4 before optimization, in case you decide to restore it back. All that is left is to delete the .old file and commit modified pk4 to SVN.

Note that xdelta3 provides only rough estimate on the diff size, because 1) SVN uses xdelta 1 instead of xdelta 3, and 2) SVN uses window size = 100 KB, while command-line xdelta3 does not allow windows size smaller than 512 KB. However, the diff size displayed by the script should be very close to diff size on the SVN server in most cases.

For programmers: the source code for pk4diffexe is located in <tt>devel/pk4diff/src</tt>.
It requires CMake and Conan to be built.
File <tt>conan_install.bat</tt> contains commands used to build it.

=== Trash ===

Optimized pk4 file contains "trash" files.
They are located in <tt>__trash__</tt> directory and have filenames <tt>trashKKK._tbin</tt>.
Since they have weird extension, they should never affect how TDM game works.

If the total amount of trash is less than 100 KB, then you can safely delete it using 7-zip program before committing update.
When the total amount of trash is more than 100 KB, then SVN diff algorithm will be broken if you delete it, most likely resulting in maximum-size diff.
Indeed, we should control amount of trash in order to achieve balance between reducing SVN storage on server and reducing download traffic and storage on players' machines.
That's why pk4diff script only accepts optimized package if amount of trash is lower than 10%.

= References =
* Thread on developer subforum: https://forums.thedarkmod.com/index.php?/topic/20624-store-missions-archive-in-svn/

Security Camera (2.10+)

2022-07-16T14:05:41Z

Dragofer:

==Security Camera==

This article documents the security camera as it will be from 2.10 onwards. See [[Security Camera]] if you're currently working with TDM 2.09 or older versions.

The security camera provides the following features:

* It can either sweep back and forth between two angles or remain stationary.
* If the camera sees the player, an AI on a hostile team or a body, it plays a short alert sound that is silent to nearby guards. If the enemy or body is still in view several seconds later, an alarm sounds. This alarm will repeat every few seconds for a while, even if the enemy moves out of sight.
* The camera is able to track its enemy, making it much harder to escape its view.
* An optional spotlight that points forward, lighting the area in the direction the camera faces.
* The ability to toggle the camera power on/off by triggering it. Each of the above described subsystems can be toggled individually.
* If the camera has targets, these will be activated when the camera is fully alerted. This gives the map author the ability to play a more powerful alarm than the one given off by the camera (or to do a variety of other things.)
* Sending what it sees to a separate, func_static display screen. Alternatively, it can send what another entity (typically a target_null) sees.

==The Security Camera: Entities and Prefabs==

Security camera entities can be found in ''AI/Machines/Security Camera'' and inherit from ''func_securitycamera''. Prefabs can be found in ''AI/Machines''.

Place the camera entity in your map, and orient it toward its starting direction. A rotating camera will sweep clockwise, halt a moment, then sweep back counter-clockwise.

Some cameras may be designed to use additional parts, i.e. a ceiling pivot entity with scripted gears. See the prefabs or the entity descriptions for more info.

==Spawnargs==

===Movement Spawnargs===

* "rotate" - If "1" (default) the camera will rotate. If "0", the camera is stationary.
* "sweepSpeed" - Horizontal rotation speed in degrees per second.
* "sweepAngle" - The number of degrees the camera covers during its sweep. You can cause a camera to initially sweep in the counter-clockwise direction by setting this to a negative number.
* "sweepWait" - How long the pause is after the end of a sweep. Default is 0.5 seconds.
* "sweepWaitSoundOffset" - Start playing snd_end before the camera reaches the end of its sweep, by this amount of seconds.

===Detection Spawnargs===

These spawnargs govern how the security camera detects and reacts to enemies: max detection distance, at what light intensity, how long the alarm lasts, whether to trigger anything and so on.

* "scanDist" - The distance limit for spotting the enemy.
* "scanFov" - The camera's field of view.
* "seePlayer" - Whether the camera will react to the player.
* "seeAI" - Whether the camera will react to AIs, and what their relationship to the camera's team has to be.
* "seeBodies" - Whether the camera will react to bodies.
* "seeAnimals" - Whether the camera will react to animals.
* "sight_threshold" - From 0.0 to 1.0, how lit up the lightgem has to be for the player to be detected.
* "sightTime" - After seeing the enemy (partial alert), the camera will wait this amount of time. If it still sees the enemy, it will sound the alarm. This gives the enemy some time to hide.
* "sightResume" - If the camera can't see the enemy anymore after a partial alert, pause for this amount of time. When this expires, the camera will resume sweeping.
* "alarm_duration" - Minimum duration of the fully alert state. Will be extended by half if the enemy is still in view at the end or was recently seen.
* "alarm_interval" - Amount of time inbetween each activation of the alarm sound, when fully alerted.
* "trigger_alarm_start" - Trigger targets when an alarm begins.
* "trigger_alarm_end" - Trigger targets when an alarm ends.

===Follow Spawnargs===

The security camera can track the enemy's movements. For as long as the security camera is partially or fully alerted, it will turn to the closest enemy it can see. The models for the camera and mount should be able to support this without clipping into each other. A ceiling-mounted camera will generally have much more freedom to turn than a wall-mounted camera.

* "follow" - Enable to let the camera track the enemy horizontally.
* "follow_tolerance" - How far in degrees the enemy has to move before the camera readjusts its rotation, horizontally.
* "follow_speed_mult" - Speed up horizontal movements by this multiplier when the camera is following the enemy.
* "follow_incline" - The camera will also track the enemy vertically.
* "follow_incline_tolerance" - How far in degrees the enemy has to move before the camera readjusts its rotation, vertically.
* "follow_incline_speed" - Speed of vertical movements to track the enemy. Not affected by 'follow_speed_mult'.
* "follow_constrain_up" - Limit how far the camera can turn upwards from its starting orientation.
* "follow_constrain_down" - Limit how far the camera can turn downwards from its starting orientation.

===Spotlight Spawnargs===

If "spotLight" is set to 1, the security camera's code will spawn a spotlight and align it with its view. This dates back to the Doom 3 days, so it follows different rules from the def_attach systems. If "useColors" is enabled, the spotlight's color will change depending on alert state. Otherwise it will look for a "_color" spawnarg on the camera.

Alternatively you can specify an existing light with the spawnarg "spotlight_custom". Apart from "spotLight" and "useColors", all other spotlight-relevant spawnargs are ignored. If no valid entity of spawnclass idLight is found, it'll spawn a spotlight instead.

* "spotLight" - If "1" the camera will use a spotlight.
* "spotlight_range" - Reach of the spotlight.
* "spotlight_diameter" - Diameter of the spotlight's projection. If 0, will automatically be calculated to match spotlight_range and scanFov, for scanFov up to 90°.
* "spotlight_texture" - Texture used by the spotlight. You should use a texture that's designed for projected lights: one that uses a gradient as its falloff image. This ensures that light intensity gradually fades to black, rather than abruptly cutting to black.
* "spotlight_volumetric" - The spawned spotlight will be volumetric.

===Color Spawnargs===

* "useColors" - If "1" the camera will change the colour of its model and spotlight depending on its alert state.
* "color_sweeping" - Color when the camera is sweeping = unalerted. Default green.
* "color_sighted" - Color when the camera has noticed an enemy = partially alerted. Default yellow.
* "color_alerted" - Color when the camera has sounded the alarm = fully alerted. Default red.
* "_color" - If "useColors" is disabled, the model and spotlight will always have this color.

As an alternative or complement to color spawnargs, you may make use of shaderParm7 in materials used by the security camera. shaderParm7 represents the alert state of the camera:
* 0 = unalerted
* 1 = was partially alerted for "sightTime" seconds but the enemy has disappeared, now waiting "sightResume" seconds before resuming sweeping.
* 2 = partially alerted
* 3 = fully alerted

===Damage Spawnargs===

* "health" - amount of damage the camera can take before being destroyed. Setting to 0 will make the camera invincible. Setting to 0 will make the camera invincible. Default base damage per hit: sword - 42; broadhead - 35; fire arrow direct hit - 400.
* "damage_blackjack" - how much damage the security camera takes from blackjack hits, default: 0.
* "damage_mult_" - a series of spawnargs to multiply how much damage the security camera takes from various damage sources. You can name specific weapon classnames or damageDefs in the spawnarg, i.e. "damage_mult_atdm:weapon_shortsword" "0.5".
* "damage_splash_falloff" - how quickly splash damage from fire arrows exponentially decreases with distance, default: 3.
* "damage_flinderize" - if a security camera is destroyed and the destroying hit (or post-destruction hit) is greater than this value, the security camera explodes into pieces. Default: 90.
* "def_flinder1" - the classname of the flinder pieces generated when a camera is flinderized by a heavy hit. Use "def_flinder2" etc. to generate more flinders.
* "flinder_offset1" - specifies the spawn point of the respective flinder piece relative to the camera's origin. Takes the camera's current rotation into account.
* "broken" - the security camera switches to this model when destroyed
* "broken_flinderized" - Optional. Specify the model of the security camera when destroyed + flinderized.
* "skin_broken" - the security camera switches to this skin when destroyed
* "skin_flinderized" - Optional. Specify the skin of the security camera when destroyed + flinderized.
* "hideModelOnBreak" - the security camera will be hidden when destroyed, default: 0.
* "notice_destroyed" - Whether AIs will become alerted if they find this security camera destroyed.
* "fx_damage" - Fx to play whenever the camera is damaged while power is on.
* "fx_damage_nopower" - Fx to play whenever the camera is damaged while power is off.
* "fx_destroyed" - Fx to play whenever the camera is destroyed while power is on.
* "fx_destroyed_nopower" - Fx to play whenever the camera is destroyed while power is off.
* "break_up_script" - This script is called when the camera is destroyed.
* "break_up_target" - This entity is triggered if the camera is destroyed.

===Sound Spawnargs===

* "snd_sight" - Sound emitted when the camera notices an enemy.
* "snd_moving" - Sound emitted when the camera is rotating.
* "snd_stationary" - Sound emitted by a stationary type of camera.
* "snd_alert" - Alarm sound emitted when fully alerted.
* "snd_end" - Sound emitted when the camera is about to reach the end point of a sweep.
* "snd_death" - Sound emitted when the camera is destroyed.
* "snd_death_nopower" - Sound emitted when the camera is destroyed while power is off.
* "snd_sparks" - Sound emitted when the camera emits sparks after it was destroyed.
* "sprS_alert" - How far snd_alert propagates to AIs, at default this is a few rooms. Higher settings than mild can cause large framedrops due to mass AI alerts.

===Sparks Spawnargs===

The security camera spawns a particle emitter when it's destroyed. By default it uses a single-cycle spark particle which is periodically triggered at random intervals. When power to the camera is switched off, the sparks stop appearing.

* "sparks" - Whether to spawn a particle emitter at all.
* "sparks_particle" - Particle that is spawned.
* "sparks_delay" - Time taken for the particle emitter to spawn initially.
* "sparks_power_dependent" - Only show the particle if power to the destroyed camera is on.
* "sparks_interval" - For non-looping particles, minimum time between triggers.
* "sparks_interval_rand" - For non-looping particles, additional random factor added to the time between triggers.

===Model Spawnargs===

These spawnargs are important if you change the camera model:

* "broken" - Use this model when the camera is destroyed.
* "viewOffset" - A vector that defines the offset of the camera's 'eye' from the camera's origin.
* "lightOffset" - A vector that defines the spotlight offset from the camera's origin.
* "flipAxis" - This and the next spawnarg can be used to turn a model such that it faces forwards. Not needed if the model was created forward-facing.
* "modelAxis"
* "skin" - This is the "on" skin. It may contain materials that make use of the colored keyword or shaderParm7, to change depending on alert state.
* "skin_on_spotlight_off" - This is the "on" skin, but with the spotlight toggled off. This is useful if your model contains inbuilt lightrays that should represent the spotlight.
* "skin_off" - This is the "off" skin. It should not contain materials with the colored keyword or shaderParm7.
* "skin_broken" - When the camera is destroyed it will switch to this skin.

===Misc Spawnargs===

* "start_off" - Whether the camera starts powered on or off.
* "cameraTarget" - Use the view from this entity instead of from self if sending a view to the display screen. See section ''The Display Screen'' for more.
* "gearSpeed" - This spawnarg is set on the ceiling pivot of the 2nd type of security camera. It controls how fast the gears turn when the security camera turns.
* "legacy" - This marks an old version of the security camera, for backwards compatibility with older missions.

The security camera uses spawnargs to place its 'eye' and spotlight in front of the model to ensure the view and spotlight aren't blocked by the model. If you use a different model, you might need to change these.
* "lightOffset"
* "viewOffset"

==Damaging the Camera==

===Damage sources===

By default the security camera is vulnerable only to fire arrows (direct & splash damage). The "damage_" and "damage_mult_" spawnargs allow you to to specify how much damage security cameras take from each weapon, but be sure to communicate the camera's vulnerabilities to the player. You can create your own "damage_mult_" spawnargs by adding the name of a specific weapon classname or damageDef, i.e. "damage_mult_atdm:weapon_shortsword" "0.5". Unfortunately it does not appear to be possible to make water damage the camera, since TDM will crash upon load when a water response is applied to the camera.

Setting "health" to 0 will make the camera totally invicible. Alternatively, you can make the camera immune to everything but fire arrow splash damage by binding a tight-fitting nodrawsolid_metal brush. A similar approach is to bind a brush that leaves parts of the camera exposed, i.e. the lens or face. Note that it will weaken fire arrows considerably if they hit from the wrong angle. A direct hit does up to 400 damage, while the splash does a distance-dependent amount of damage below 100. Note that collision detection is done using the camera's clipmodel, which has a different shape than the visual model.

The player will receive feedback that the camera took damage in the form of spark effects, specified in spawnargs beginning with fx_. An .fx definiton is basically an instruction to emit a sequence of particles and sounds.

===Destroying the Camera===

Security cameras can not only be destroyed, but also be flinderized (burst apart into pieces) which occurs when the security camera takes a hit whose damage is higher than the value of the "damage_flinderize" spawnarg. The "broken" and "skin_broken" spawnargs let you set the model and skin when the camera is destroyed, while the optional "broken_flinderized" and "skin_flinderized" let you set the model and skin when the camera has been flinderized. The "def_flinder" and "flinder_offset" spawnargs allow you to specify the flinder pieces and their spawn point relative to the camera's origin.

==Scripting==

===Script Events===

The security camera supports the following script events:
* getSecurityCameraState() - Returns the security camera's state. 1 = unalerted, 2 = partially alerted, 3 = fully alerted, 4 = inactive (power off), 5 = destroyed, 0 = not a security camera.
* getShaderParm(7) - Returns the current value of shaderParm7 on the camera model. 0 = unalerted, 1 = about to resume sweep after a partial alert, 2 = partially alerted, 3 = fully alerted.
* On() and Off() - Switch the camera's power on or off (note the capitalisation).
* activate() and trigger() - Toggle the camera's power.
* getHealth() and setHealth(float newHealth) - As per the name. Setting health to 0 or lower will destroy the security camera, which is irreversible. setHealth() will make an invincible camera vulnerable.
* getEnemy() - Returns the entity that most recently caused or refreshed the security camera's suspicious or alert state.
* canSee() - Tests whether the security camera is able to see a specific entity. Currently only player1 is supported.
* setSightThreshold() - This changes how lit up the player's lightgem has to be for the security camera to see him, from 0.0 to 1.0.
* state_light(boolean set) - Switch the camera's spotlight on/off, if the camera has one.
* state_sweep(boolean set) - Switch the camera's sweep on/off. This will also affect enemy tracking.
* state_see_player(boolean set) - Toggle whether the camera is able to detect the player. An alternative is just to set "seePlayer" to "1" or "0", since the code monitors this spawnarg.
* toggle_light() - Toggle the spotlight on/off, if the camera has one.
* toggle_sweep() - Toggle the camera's sweep on/off. This will also affect enemy tracking.
* toggle_see_player() - Toggle whether the camera is able to detect the player. An alternative is just to set "seePlayer" to "1" or "0", since the code monitors this spawnarg.

===Object Functions===

The security camera's scriptobject contains the following object functions:
* toggleSCSpotlight() - calls toggle_light() on the camera if it has a spotlight (spawnarg "spotLight" = "1")
* toggleSCSweep() - calls toggle_sweep() on the camera
* toggleSCPlayer() - calls toggle_see_player() on the camera

As you can see, these object functions simply call the toggle script events on the camera they belong to. This allows you to call the script events from i.e. buttons without scripting. To set this up:
# create an atdm:target_callobjectfunction entity
# give it the spawnarg "call" with the name of the desired object function, i.e. "toggleSCSpotlight"
# let it target the security camera
# when desired, trigger this entity (from a script, from a button etc.).

===Scriptobjects===

The security camera's scriptobject only consists of the 3 object functions mentioned above. Beyond some added utility, this scriptobject has no importance for the security camera and you can easily give it your own scriptobject instead.

===Upon Destruction===

You may call a script when the camera is destroyed, as per the spawnarg "break_up_script". This script should be able to receive the name of the destroyed security camera as input, i.e.:
void camera_destroyed ( entity camera )

An alternative is to use the spawnarg "break_up_target" to name an entity that calls the script when triggered, but this will not pass the name of the destroyed security camera unless you use an atdm:target_callscriptfunction entity with the spawnarg "forEach" "1".

==Sending the camera's view to a Display Screen==

You can create a display screen that shows that the camera sees: all that's needed is a func_static patch that uses a texture like ''textures/common/camera/camera1''. It's recommended to put another patch behind it, since this func_static will get hidden if it's switched off. The screen then needs to be given a spawnarg "cameraTarget" that names either a security camera or a different entity, typically a target_null. The screen will display what that entity sees.

To change the screen's field of view, apply the spawnargs "cameraFovX" and "cameraFovY" to the entity sending the view. Otherwise it will default to "scanFov" for security cameras or 120 for other entities.

The screen is hidden or shown automatically if the screen is displaying a security camera's view. The screen can also be switched on/off manually by triggering it, but this requires the screen to start with the spawnarg "hide" "0" or "hide" "1".

===Multiple Display Screens / Reflective Water / Skybox===

If you plan to have multiple security cameras sending to multiple display screens in your mission, or if the camera display will appear in the same player POV as the sky or reflective water surfaces, you'll need to use unique camera materials for each screen. You can find 9 additional camera materials in the textures/common/camera/ folder. If you should need even more, you can simply clone one of the materials and change the name after the ''map'' keyword.

==Examining a Test Map==

You can obtain a test map with sample cameras in it here: [https://ftp.thedarkmod.com/tutorials/RemoteCamera/camerawiki2.pk4 camerawiki2.pk4]. Similar setups can be found as prefabs in AI/Machines.

Open the map ''camerawiki.map'' in Dark Radiant. In this map, we have examples of the different cameras.

[[Image:Cw1.jpg|256px|thumb|right|cam1]]

'''A rotating camera that sweeps back and forth'''

This camera (''cam1'') starts its rotation at 135 degrees (assuming +X is 0 degrees), and sweeps clockwise until it reaches 45 degrees. It pauses for a moment, then return-sweeps back to 135 degrees. It has a spotlight.

The display for ''cam1'' is on the wall behind it. (Don't worry about the material being displayed backward in the screenshot.)

The display patch uses the material ''camera1'' (provided in the camerawiki/materials/tdm_camera.mtr file).

The four buttons below the display do the following (from left to right):

* Toggle Power - targets ''cam1'' directly. When power is off, the display screen is hidden. You can simulate an "off" screen by making sure there's a black material behind the display. You could also place a glass material behind the display.
* Toggle Spotlight - calls the ''toggleSCSpotlight()'' object function in the camera's scriptobject, turning the spotlight on/off
* Toggle Player Sighting - calls the ''toggleSCPlayer()'' object function in the camera's scriptobject, turning Player detection on/off
* Toggle Sweep - calls the ''toggleSCSweep()'' object function in the camera's scriptobject, turning camera sweep on/off

[[Image:Cw2.jpg|256px|thumb|right|cam1's display]]
{{clear}}
'''A stationary camera that doesn't move'''

[[Image:Cw3.jpg|320px|thumb|right|cam2 and its display]]
This camera (''cam2'') is stationary, w/o a spotlight.

Its display, to its left, uses the material ''camera2''.

The two buttons below the display do the following (from left to right):

* Toggle Power - targets ''cam2'' directly. When power is off, the display screen is hidden.
* Toggle Player Sighting - calls the ''toggleSCPlayer()'' object function in the camera's scriptobject, turning player detection on/off
{{clear}}

'''A screen showing the view from another entity (a target_null)'''

[[Image:Cw6.jpg|320px|thumb|right|a small screen showing what a target_null is seeing]]

This is simply a screen referencing a ''target_null'' as its ''cameraTarget''. The ''target_null'' is in a separate room pointed at a guard.

If you look in the room where the guard is standing, you'll see that the ''target_null'' has the spawnargs ''cameraFovX'' and ''cameraFovY''. These were set because the default field of view for a view from a non-camera entity is 120 by 120, which looks quite zoomed out. For a small screen like this one, 60 by 60 is much better.

Also notice that the screen itself has the spawnarg ''hide'' ''0''. This makes it respond to triggers by hiding or showing itself, allowing you to switch it on or off at the push of a button (see below).

The button below the display does the following:

* Toggle Power - targets the screen directly to show or hide it. This only works because the screen has a ''hide'' spawnarg.

{{clear}}
[[Category:Editing]]

Security Camera (2.10+)

2022-07-16T13:58:47Z

Dragofer:

==Security Camera==

This article documents the security camera as it will be from 2.10 onwards. See [[Security Camera]] if you're currently working with TDM 2.09 or older versions.

The security camera provides the following features:

* It can either sweep back and forth between two angles or remain stationary.
* If the camera sees the player or an AI on a hostile AI, it initially plays a short alert sound that is silent to nearby guards. If the enemy is still in view several seconds later, an alarm sounds. This alarm will play intermittently for a while, even if the enemy moves out of sight.
* The camera is able to track its enemy, making it much harder to escape its view.
* An optional spotlight that points forward, lighting the area in the direction the camera faces. You can instead let the camera use a light you created.
* The ability to toggle the camera power on/off by triggering it. Alternatively, the above described subsystems can be toggled individually.
* If the camera has targets, these will be activated when the camera is fully alerted. This gives the map author the ability to play a more powerful alarm than the one given off by the camera (or to do a variety of other things.)
* The camera will sound an alarm if it detects bodies.
* Sending what it sees to a separate, func_static display screen. Alternatively, it can send what another entity (typically a target_null) sees.

==The Security Camera: Entities and Prefabs==

Security camera entities can be found in ''AI/Machines/Security Camera'' and inherit from ''func_securitycamera''. Prefabs can be found in ''AI/Machines''.

Place the camera entity in your map, and orient it toward its starting direction. A rotating camera will sweep clockwise, halt a moment, then sweep back counter-clockwise.

Some cameras may be designed to use additional parts, i.e. a ceiling pivot entity with scripted gears. See the entity descriptions inside DR for more.

==Spawnargs==

===Movement Spawnargs===

* "rotate" - If "1" (default) the camera will rotate. If "0", the camera is stationary.
* "sweepSpeed" - Horizontal rotation speed in degrees per second.
* "sweepAngle" - The number of degrees the camera covers during its sweep. You can cause a camera to initially sweep in the counter-clockwise direction by setting this to a negative number.
* "sweepWait" - How long the pause is after a sweep completes and starting the return sweep. Default is 0.5 seconds.
* "sweepWaitSoundOffset" - Start playing snd_end before the camera reaches the end of its sweep, by this amount of seconds.

===Detection Spawnargs===

These spawnargs govern how the security camera detects and reacts to the player: up to what distance, at what light intensity, how long the alarm lasts, whether to trigger anything and so on.

* "scanDist" - The distance limit for spotting the enemy.
* "scanFov" - The camera's field of view.
* "seePlayer" - Whether the camera will react to the player.
* "seeAI" - Whether the camera will react to AIs.
* "seeBodies" - Whether the camera will react to bodies.
* "seeAnimals" - Whether the camera will react to animals.
* "sight_threshold" - From 0.0 to 1.0, how lit up the lightgem has to be for the player to be detected.
* "sightTime" - After seeing the enemy (partial alert), the camera will wait this amount of time. If it still sees the enemy, it will sound the alarm. This gives the enemy some time to hide.
* "sightResume" - If the camera can't see the enemy anymore after a partial alert, pause for this amount of time. When this expires, the camera will resume sweeping.
* "alarm_duration" - Minimum duration of the fully alert state. Will be extended by half if the enemy is still in view at the end or was recently seen.
* "alarm_interval" - Amount of time inbetween each activation of the alarm sound, when fully alerted.
* "trigger_alarm_start" - Trigger targets when an alarm begins.
* "trigger_alarm_end" - Trigger targets when an alarm ends.

===Follow Spawnargs===

The security camera can track the enemy's movements. For as long as the security camera is partially or fully alerted, it will turn to the closest enemy it can see. The models for the camera and mount should be able to support this without clipping into each other. A ceiling-mounted camera will generally have much more freedom to turn than a wall-mounted camera.

* "follow" - Enable to let the camera track the enemy horizontally.
* "follow_tolerance" - How far in degrees the enemy has to move before the camera readjusts its rotation, horizontally.
* "follow_speed_mult" - Speed up horizontal movements by this multiplier when the camera is following the enemy.
* "follow_incline" - The camera will also track the enemy vertically.
* "follow_incline_tolerance" - How far in degrees the enemy has to move before the camera readjusts its rotation, vertically.
* "follow_incline_speed" - Speed of vertical movements to track the enemy. Not affected by 'follow_speed_mult'.
* "follow_constrain_up" - Limit how far the camera can turn upwards from its starting orientation.
* "follow_constrain_down" - Limit how far the camera can turn downwards from its starting orientation.

===Spotlight Spawnargs===

If "spotLight" is set to 1, the security camera's code will spawn a spotlight and align it with its view. This dates back to the Doom3 days, so it follows different rules from the def_attach systems. If "useColors" is enabled, the spotlight's color will change depending on alert state. Otherwise it will look for a "_color" spawnarg on the camera.

Alternatively you can specify an existing light with the spawnarg "spotlight_custom". Apart from "spotLight" and "useColors", all other spotlight-relevant spawnargs are ignored. If no valid entity of spawnclass idLight is found, it'll spawn a spotlight instead.

* "spotLight" - If "1" the camera will use a spotlight.
* "spotlight_range" - Reach of the spotlight.
* "spotlight_diameter" - Diameter of the spotlight's projection. If 0, will automatically be calculated to match spotlight_range and scanFov, for scanFov up to 90°.
* "spotlight_texture" - Texture used by the spotlight. You should use a texture that's designed for projected lights: one that uses a gradient as its falloff image. This ensures that light intensity gradually fades to black, rather than abruptly cutting to black.
* "spotlight_volumetric" - The spawned spotlight will be volumetric.

===Color Spawnargs===

* "useColors" - If "1" the camera will change the colour of its model and spotlight depending on its alert state.
* "color_sweeping" - Color when the camera is sweeping = unalerted. Default green.
* "color_sighted" - Color when the camera has noticed an enemy = partially alerted. Default yellow.
* "color_alerted" - Color when the camera has sounded the alarm = fully alerted. Default red.
* "_color" - If "useColors" is disabled, the model and spotlight will always have this color.

As an alternative or complement to color spawnargs, you may make use of shaderParm7 in materials used by the security camera. shaderParm7 represents the alert state of the camera:
* 0 = unalerted
* 1 = was partially alerted for "sightTime" seconds but the enemy has disappeared, now waiting "sightResume" seconds before resuming sweeping.
* 2 = partially alerted
* 3 = fully alerted

===Damage Spawnargs===

* "health" - amount of damage the camera can take before being destroyed. Setting to 0 will make the camera invincible. Setting to 0 will make the camera invincible. Default base damage per hit: sword - 42; broadhead - 35; fire arrow direct hit - 400.
* "damage_blackjack" - how much damage the security camera takes from blackjack hits, default: 0.
* "damage_mult_" - a series of spawnargs to multiply how much damage the security camera takes from various damage sources. You can name specific weapon classnames or damageDefs in the spawnarg, i.e. "damage_mult_atdm:weapon_shortsword" "0.5".
* "damage_splash_falloff" - how quickly splash damage from fire arrows exponentially decreases with distance, default: 3.
* "damage_flinderize" - if a security camera is destroyed and the destroying hit (or post-destruction hit) is greater than this value, the security camera explodes into pieces. Default: 90.
* "def_flinder1" - the classname of the flinder pieces generated when a camera is flinderized by a heavy hit. Use "def_flinder2" etc. to generate more flinders.
* "flinder_offset1" - specifies the spawn point of the respective flinder piece relative to the camera's origin. Takes the camera's current rotation into account.
* "broken" - the security camera switches to this model when destroyed
* "broken_flinderized" - Optional. Specify the model of the security camera when destroyed + flinderized.
* "skin_broken" - the security camera switches to this skin when destroyed
* "skin_flinderized" - Optional. Specify the skin of the security camera when destroyed + flinderized.
* "hideModelOnBreak" - the security camera will be hidden when destroyed, default: 0.
* "notice_destroyed" - Whether AIs will become alerted if they find this security camera destroyed.
* "fx_damage" - Fx to play whenever the camera is damaged while power is on.
* "fx_damage_nopower" - Fx to play whenever the camera is damaged while power is off.
* "fx_destroyed" - Fx to play whenever the camera is destroyed while power is on.
* "fx_destroyed_nopower" - Fx to play whenever the camera is destroyed while power is off.
* "break_up_script" - This script is called when the camera is destroyed.
* "break_up_target" - This entity is triggered if the camera is destroyed.

===Sound Spawnargs===

* "snd_sight" - Sound emitted when the camera notices an enemy.
* "snd_moving" - Sound emitted when the camera is rotating.
* "snd_stationary" - Sound emitted by a stationary type of camera.
* "snd_alert" - Alarm sound emitted when fully alerted.
* "snd_end" - Sound emitted when the camera is about to reach the end point of a sweep.
* "snd_death" - Sound emitted when the camera is destroyed.
* "snd_death_nopower" - Sound emitted when the camera is destroyed while power is off.
* "snd_sparks" - Sound emitted when the camera emits sparks after it was destroyed.
* "sprS_alert" - How far snd_alert propagates to AIs, at default this is a few rooms. Higher settings than mild can cause large framedrops due to mass AI alerts.

===Sparks Spawnargs===

The security camera spawns a particle emitter when it's destroyed. By default it uses a single-cycle spark particle which is periodically triggered at random intervals. When power to the camera is switched off, the sparks stop appearing.

* "sparks" - Whether to spawn a particle emitter at all.
* "sparks_particle" - Particle that is spawned.
* "sparks_delay" - Time taken for the particle emitter to spawn initially.
* "sparks_power_dependent" - Only show the particle if power to the destroyed camera is on.
* "sparks_interval" - For non-looping particles, minimum time between triggers.
* "sparks_interval_rand" - For non-looping particles, additional random factor added to the time between triggers.

===Model Spawnargs===

These spawnargs are important if you change the camera model:

* "broken" - Use this model when the camera is destroyed.
* "viewOffset" - A vector that defines the offset of the camera's 'eye' from the camera's origin.
* "lightOffset" - A vector that defines the spotlight offset from the camera's origin.
* "flipAxis" - This and the next spawnarg can be used to turn a model such that it faces forwards. Not needed if the model was created forward-facing.
* "modelAxis"
* "skin" - This is the "on" skin. It may contain materials that make use of the colored keyword or shaderParm7, to change depending on alert state.
* "skin_on_spotlight_off" - This is the "on" skin, but with the spotlight toggled off. This is useful if your model contains inbuilt lightrays that should represent the spotlight.
* "skin_off" - This is the "off" skin. It should not contain materials with the colored keyword or shaderParm7.
* "skin_broken" - When the camera is destroyed it will switch to this skin.

===Misc Spawnargs===

* "start_off" - Whether the camera starts powered on or off.
* "cameraTarget" - Use the view from this entity instead of from self if sending a view to the display screen. See section ''The Display Screen'' for more.
* "gearSpeed" - This spawnarg is set on the ceiling pivot of the 2nd type of security camera. It controls how fast the gears turn when the security camera turns.
* "legacy" - This marks an old version of the security camera, for backwards compatibility with older missions.

The security camera uses spawnargs to place its 'eye' and spotlight in front of the model to ensure the view and spotlight aren't blocked by the model. If you use a different model, you might need to change these.
* "lightOffset"
* "viewOffset"

==Damaging the Camera==

===Damage sources===

By default the security camera is vulnerable only to fire arrows (direct & splash damage). The "damage_" and "damage_mult_" spawnargs allow you to to specify how much damage security cameras take from each weapon, but be sure to communicate the camera's vulnerabilities to the player. You can create your own "damage_mult_" spawnargs by adding the name of a specific weapon classname or damageDef, i.e. "damage_mult_atdm:weapon_shortsword" "0.5". Unfortunately it does not appear to be possible to make water damage the camera, since TDM will crash upon load when a water response is applied to the camera.

Setting "health" to 0 will make the camera totally invicible. Alternatively, you can make the camera immune to everything but fire arrow splash damage by binding a tight-fitting nodrawsolid_metal brush. A similar approach is to bind a brush that leaves parts of the camera exposed, i.e. the lens or face. Note that it will weaken fire arrows considerably if they hit from the wrong angle. A direct hit does up to 400 damage, while the splash does a distance-dependent amount of damage below 100. Note that collision detection is done using the camera's clipmodel, which has a different shape than the visual model.

The player will receive feedback that the camera took damage in the form of spark effects, specified in spawnargs beginning with fx_. An .fx definiton is basically an instruction to emit a sequence of particles and sounds.

===Destroying the Camera===

Security cameras can not only be destroyed, but also be flinderized (burst apart into pieces) which occurs when the security camera takes a hit whose damage is higher than the value of the "damage_flinderize" spawnarg. The "broken" and "skin_broken" spawnargs let you set the model and skin when the camera is destroyed, while the optional "broken_flinderized" and "skin_flinderized" let you set the model and skin when the camera has been flinderized. The "def_flinder" and "flinder_offset" spawnargs allow you to specify the flinder pieces and their spawn point relative to the camera's origin.

==Scripting==

===Script Events===

The security camera supports the following script events:
* getSecurityCameraState() - Returns the security camera's state. 1 = unalerted, 2 = partially alerted, 3 = fully alerted, 4 = inactive (power off), 5 = destroyed, 0 = not a security camera.
* getShaderParm(7) - Returns the current value of shaderParm7 on the camera model. 0 = unalerted, 1 = about to resume sweep after a partial alert, 2 = partially alerted, 3 = fully alerted.
* On() and Off() - Switch the camera's power on or off (note the capitalisation).
* activate() and trigger() - Toggle the camera's power.
* getHealth() and setHealth(float newHealth) - As per the name. Setting health to 0 or lower will destroy the security camera, which is irreversible. setHealth() will make an invincible camera vulnerable.
* getEnemy() - Returns the entity that most recently caused or refreshed the security camera's suspicious or alert state.
* canSee() - Tests whether the security camera is able to see a specific entity. Currently only player1 is supported.
* setSightThreshold() - This changes how lit up the player's lightgem has to be for the security camera to see him, from 0.0 to 1.0.
* state_light(boolean set) - Switch the camera's spotlight on/off, if the camera has one.
* state_sweep(boolean set) - Switch the camera's sweep on/off. This will also affect enemy tracking.
* state_see_player(boolean set) - Toggle whether the camera is able to detect the player. An alternative is just to set "seePlayer" to "1" or "0", since the code monitors this spawnarg.
* toggle_light() - Toggle the spotlight on/off, if the camera has one.
* toggle_sweep() - Toggle the camera's sweep on/off. This will also affect enemy tracking.
* toggle_see_player() - Toggle whether the camera is able to detect the player. An alternative is just to set "seePlayer" to "1" or "0", since the code monitors this spawnarg.

===Object Functions===

The security camera's scriptobject contains the following object functions:
* toggleSCSpotlight() - calls toggle_light() on the camera if it has a spotlight (spawnarg "spotLight" = "1")
* toggleSCSweep() - calls toggle_sweep() on the camera
* toggleSCPlayer() - calls toggle_see_player() on the camera

As you can see, these object functions simply call the toggle script events on the camera they belong to. This allows you to call the script events from i.e. buttons without scripting. To set this up:
# create an atdm:target_callobjectfunction entity
# give it the spawnarg "call" with the name of the desired object function, i.e. "toggleSCSpotlight"
# let it target the security camera
# when desired, trigger this entity (from a script, from a button etc.).

===Scriptobjects===

The security camera's scriptobject only consists of the 3 object functions mentioned above. Beyond some added utility, this scriptobject has no importance for the security camera and you can easily give it your own scriptobject instead.

===Upon Destruction===

You may call a script when the camera is destroyed, as per the spawnarg "break_up_script". This script should be able to receive the name of the destroyed security camera as input, i.e.:
void camera_destroyed ( entity camera )

An alternative is to use the spawnarg "break_up_target" to name an entity that calls the script when triggered, but this will not pass the name of the destroyed security camera unless you use an atdm:target_callscriptfunction entity with the spawnarg "forEach" "1".

==Sending the camera's view to a Display Screen==

You can create a display screen that shows that the camera sees: all that's needed is a func_static patch that uses a texture like ''textures/common/camera/camera1''. It's recommended to put another patch behind it, since this func_static will get hidden if it's switched off. The screen then needs to be given a spawnarg "cameraTarget" that names either a security camera or a different entity, typically a target_null. The screen will display what that entity sees.

To change the screen's field of view, apply the spawnargs "cameraFovX" and "cameraFovY" to the entity sending the view. Otherwise it will default to "scanFov" for security cameras or 120 for other entities.

The screen is hidden or shown automatically if the screen is displaying a security camera's view. The screen can also be switched on/off manually by triggering it, but this requires the screen to start with the spawnarg "hide" "0" or "hide" "1".

===Multiple Display Screens / Reflective Water / Skybox===

If you plan to have multiple security cameras sending to multiple display screens in your mission, or if the camera display will appear in the same player POV as the sky or reflective water surfaces, you'll need to use unique camera materials for each screen. You can find 9 additional camera materials in the textures/common/camera/ folder. If you should need even more, you can simply clone one of the materials and change the name after the ''map'' keyword.

==Examining a Test Map==

You can obtain a test map with sample cameras in it here: [https://ftp.thedarkmod.com/tutorials/RemoteCamera/camerawiki2.pk4 camerawiki2.pk4]. Similar setups can be found as prefabs in AI/Machines.

Open the map ''camerawiki.map'' in Dark Radiant. In this map, we have examples of the different cameras.

[[Image:Cw1.jpg|256px|thumb|right|cam1]]

'''A rotating camera that sweeps back and forth'''

This camera (''cam1'') starts its rotation at 135 degrees (assuming +X is 0 degrees), and sweeps clockwise until it reaches 45 degrees. It pauses for a moment, then return-sweeps back to 135 degrees. It has a spotlight.

The display for ''cam1'' is on the wall behind it. (Don't worry about the material being displayed backward in the screenshot.)

The display patch uses the material ''camera1'' (provided in the camerawiki/materials/tdm_camera.mtr file).

The four buttons below the display do the following (from left to right):

* Toggle Power - targets ''cam1'' directly. When power is off, the display screen is hidden. You can simulate an "off" screen by making sure there's a black material behind the display. You could also place a glass material behind the display.
* Toggle Spotlight - calls the ''toggleSCSpotlight()'' object function in the camera's scriptobject, turning the spotlight on/off
* Toggle Player Sighting - calls the ''toggleSCPlayer()'' object function in the camera's scriptobject, turning Player detection on/off
* Toggle Sweep - calls the ''toggleSCSweep()'' object function in the camera's scriptobject, turning camera sweep on/off

[[Image:Cw2.jpg|256px|thumb|right|cam1's display]]
{{clear}}
'''A stationary camera that doesn't move'''

[[Image:Cw3.jpg|320px|thumb|right|cam2 and its display]]
This camera (''cam2'') is stationary, w/o a spotlight.

Its display, to its left, uses the material ''camera2''.

The two buttons below the display do the following (from left to right):

* Toggle Power - targets ''cam2'' directly. When power is off, the display screen is hidden.
* Toggle Player Sighting - calls the ''toggleSCPlayer()'' object function in the camera's scriptobject, turning player detection on/off
{{clear}}

'''A screen showing the view from another entity (a target_null)'''

[[Image:Cw6.jpg|320px|thumb|right|a small screen showing what a target_null is seeing]]

This is simply a screen referencing a ''target_null'' as its ''cameraTarget''. The ''target_null'' is in a separate room pointed at a guard.

If you look in the room where the guard is standing, you'll see that the ''target_null'' has the spawnargs ''cameraFovX'' and ''cameraFovY''. These were set because the default field of view for a view from a non-camera entity is 120 by 120, which looks quite zoomed out. For a small screen like this one, 60 by 60 is much better.

Also notice that the screen itself has the spawnarg ''hide'' ''0''. This makes it respond to triggers by hiding or showing itself, allowing you to switch it on or off at the push of a button (see below).

The button below the display does the following:

* Toggle Power - targets the screen directly to show or hide it. This only works because the screen has a ''hide'' spawnarg.

{{clear}}
[[Category:Editing]]

Security Camera (2.10+)

2022-07-16T13:39:01Z

Dragofer: Update with new script events.

==Security Camera==

This article documents the security camera as it will be from 2.10 onwards. See [[Security Camera]] if you're currently working with TDM 2.09 or older versions.

The security camera provides the following features:

* It can either sweep back and forth between two angles or remain stationary.
* If the camera sees the player or an AI on a hostile AI, it initially plays a short alert sound that is silent to nearby guards. If the enemy is still in view several seconds later, an alarm sounds. This alarm will play intermittently for a while, even if the enemy moves out of sight.
* The camera is able to track its enemy, making it much harder to escape its view.
* An optional spotlight that points forward, lighting the area in the direction the camera faces. You can instead let the camera use a light you created.
* The ability to toggle the camera power on/off by triggering it. Alternatively, the above described subsystems can be toggled individually.
* If the camera has targets, these will be activated when the camera is fully alerted. This gives the map author the ability to play a more powerful alarm than the one given off by the camera (or to do a variety of other things.)
* The camera will sound an alarm if it detects bodies.
* Sending what it sees to a separate, func_static display screen. Alternatively, it can send what another entity (typically a target_null) sees.

==The Security Camera: Entities and Prefabs==

Security camera entities can be found in ''AI/Machines/Security Camera'' and inherit from ''func_securitycamera''. Prefabs can be found in ''AI/Machines''.

Place the camera entity in your map, and orient it toward its starting direction. A rotating camera will sweep clockwise, halt a moment, then sweep back counter-clockwise.

Some cameras may be designed to use additional parts, i.e. a ceiling pivot entity with scripted gears. See the entity descriptions inside DR for more.

==Spawnargs==

===Movement Spawnargs===

* "rotate" - If "1" (default) the camera will rotate. If "0", the camera is stationary.
* "sweepSpeed" - Horizontal rotation speed in degrees per second.
* "sweepAngle" - The number of degrees the camera covers during its sweep. You can cause a camera to initially sweep in the counter-clockwise direction by setting this to a negative number.
* "sweepWait" - How long the pause is after a sweep completes and starting the return sweep. Default is 0.5 seconds.

===Detection Spawnargs===

These spawnargs govern how the security camera detects and reacts to the player: up to what distance, at what light intensity, how long the alarm lasts, whether to trigger anything and so on.

* "scanDist" - The distance limit for spotting the enemy.
* "scanFov" - The camera's field of view.
* "seePlayer" - Whether the camera will react to the player.
* "seeAI" - Whether the camera will react to AIs.
* "seeBodies" - Whether the camera will react to bodies.
* "seeAnimals" - Whether the camera will react to animals.
* "sight_threshold" - From 0.0 to 1.0, how lit up the lightgem has to be for the player to be detected.
* "sightTime" - After seeing the enemy (partial alert), the camera will wait this amount of time. If it still sees the enemy, it will sound the alarm. This gives the enemy some time to hide.
* "sightResume" - If the camera can't see the enemy anymore after a partial alert, pause for this amount of time. When this expires, the camera will resume sweeping.
* "alarm_duration" - Minimum duration of the fully alert state. Will be extended by half if the enemy is still in view at the end or was recently seen.
* "alarm_interval" - Amount of time inbetween each activation of the alarm sound, when fully alerted.
* "trigger_alarm_start" - Trigger targets when an alarm begins.
* "trigger_alarm_end" - Trigger targets when an alarm ends.

===Follow Spawnargs===

The security camera can track the enemy's movements. For as long as the security camera is partially or fully alerted, it will turn to the closest enemy it can see. The models for the camera and mount should be able to support this without clipping into each other. A ceiling-mounted camera will generally have much more freedom to turn than a wall-mounted camera.

* "follow" - Enable to let the camera track the enemy horizontally.
* "follow_tolerance" - How far in degrees the enemy has to move before the camera readjusts its rotation, horizontally.
* "follow_speed_mult" - Speed up horizontal movements by this multiplier when the camera is following the enemy.
* "follow_incline" - The camera will also track the enemy vertically.
* "follow_incline_tolerance" - How far in degrees the enemy has to move before the camera readjusts its rotation, vertically.
* "follow_incline_speed" - Speed of vertical movements to track the enemy. Not affected by 'follow_speed_mult'.
* "follow_incline_max_up" - Limit how far the camera can turn upwards from its starting orientation.
* "follow_incline_max_down" - Limit how far the camera can turn downwards from its starting orientation.

===Spotlight Spawnargs===

If "spotLight" is set to 1, the security camera's code will spawn a spotlight and align it with its view. This dates back to the Doom3 days, so it follows different rules from the def_attach systems. If "useColors" is enabled, the spotlight's color will change depending on alert state. Otherwise it will look for a "_color" spawnarg on the camera.

Alternatively you can specify an existing light with the spawnarg "spotlight_custom". Apart from "spotLight" and "useColors", all other spotlight-relevant spawnargs are ignored. If no valid entity of spawnclass idLight is found, it'll spawn a spotlight instead.

* "spotLight" - If "1" the camera will use a spotlight.
* "spotlight_range" - Reach of the spotlight.
* "spotlight_diameter" - Diameter of the spotlight's projection. If 0, will automatically be calculated to match spotlight_range and scanFov, for scanFov up to 90°.
* "spotlight_texture" - Texture used by the spotlight. You should use a texture that's designed for projected lights: one that uses a gradient as its falloff image. This ensures that light intensity gradually fades to black, rather than abruptly cutting to black.

===Color Spawnargs===

* "useColors" - If "1" the camera will change the colour of its model and spotlight depending on its alert state.
* "color_sweeping" - Color when the camera is sweeping = unalerted. Default green.
* "color_sighted" - Color when the camera has noticed an enemy = partially alerted. Default yellow.
* "color_alerted" - Color when the camera has sounded the alarm = fully alerted. Default red.
* "_color" - If "useColors" is disabled, the model and spotlight will always have this color.

As an alternative or complement to color spawnargs, you may make use of shaderParm7 in materials used by the security camera. shaderParm7 represents the alert state of the camera:
* 0 = unalerted
* 1 = was partially alerted for "sightTime" seconds but the enemy has disappeared, now waiting "sightResume" seconds before resuming sweeping.
* 2 = partially alerted
* 3 = fully alerted

===Damage Spawnargs===

* "health" - amount of damage the camera can take before being destroyed. Setting to 0 will make the camera invincible. Setting to 0 will make the camera invincible. Default base damage per hit: sword - 42; broadhead - 35; fire arrow direct hit - 400.
* "damage_blackjack" - how much damage the security camera takes from blackjack hits, default: 0.
* "damage_mult_" - a series of spawnargs to multiply how much damage the security camera takes from various damage sources. You can name specific weapon classnames or damageDefs in the spawnarg, i.e. "damage_mult_atdm:weapon_shortsword" "0.5".
* "damage_splash_falloff" - how quickly splash damage from fire arrows exponentially decreases with distance, default: 3.
* "damage_flinderize" - if a security camera is destroyed and the destroying hit (or post-destruction hit) is greater than this value, the security camera explodes into pieces. Default: 90.
* "def_flinder1" - the classname of the flinder pieces generated when a camera is flinderized by a heavy hit. Use "def_flinder2" etc. to generate more flinders.
* "flinder_offset1" - specifies the spawn point of the respective flinder piece relative to the camera's origin. Takes the camera's current rotation into account.
* "broken" - the security camera switches to this model when destroyed
* "broken_flinderized" - Optional. Specify the model of the security camera when destroyed + flinderized.
* "skin_broken" - the security camera switches to this skin when destroyed
* "skin_flinderized" - Optional. Specify the skin of the security camera when destroyed + flinderized.
* "hideModelOnBreak" - the security camera will be hidden when destroyed, default: 0.
* "notice_destroyed" - Whether AIs will become alerted if they find this security camera destroyed.
* "fx_damage" - Fx to play whenever the camera is damaged while power is on.
* "fx_damage_nopower" - Fx to play whenever the camera is damaged while power is off.
* "fx_destroyed" - Fx to play whenever the camera is destroyed while power is on.
* "fx_destroyed_nopower" - Fx to play whenever the camera is destroyed while power is off.
* "break_up_script" - This script is called when the camera is destroyed.
* "break_up_target" - This entity is triggered if the camera is destroyed.

===Sound Spawnargs===

* "snd_sight" - Sound emitted when the camera notices an enemy.
* "snd_moving" - Sound emitted when the camera is rotating.
* "snd_stationary" - Sound emitted by a stationary type of camera.
* "snd_alert" - Alarm sound emitted when fully alerted.
* "snd_end" - Sound emitted when the camera is about to reach the end point of a sweep.
* "snd_death" - Sound emitted when the camera is destroyed.
* "snd_death_nopower" - Sound emitted when the camera is destroyed while power is off.
* "snd_sparks" - Sound emitted when the camera emits sparks after it was destroyed.
* "sprS_alert" - How far snd_alert propagates to AIs, at default this is a few rooms. Higher settings than mild can cause large framedrops due to mass AI alerts.

===Sparks Spawnargs===

The security camera spawns a particle emitter when it's destroyed. By default it uses a single-cycle spark particle which is periodically triggered at random intervals. When power to the camera is switched off, the sparks stop appearing.

* "sparks" - Whether to spawn a particle emitter at all.
* "sparks_particle" - Particle that is spawned.
* "sparks_delay" - Time taken for the particle emitter to spawn initially.
* "sparks_power_dependent" - Only show the particle if power to the (dead) camera is on.
* "sparks_periodic" - Set to '0' if you use a looping particle and sound. For single-cycle particles and sounds, set to '1' so that they are regularly triggered.
* "sparks_interval" - For non-looping particles, minimum time between triggers.
* "sparks_interval_rand" - For non-looping particles, additional random factor added to the time between triggers.

===Model Spawnargs===

These spawnargs are important if you change the camera model:

* "broken" - Use this model when the camera is destroyed.
* "clipmodel" - Assign a simplified collision mesh to this camera. Should be under 32 tris (as of TDM 2.10), have only convex angles and use textures/common/collision.
* "viewOffset" - A vector that defines the offset of the camera's 'eye' from the camera's origin.
* "lightOffset" - A vector that defines the spotlight offset from the camera's origin.
* "flipAxis" - This and the next spawnarg can be used to turn a model such that it faces forwards. Not needed if the model was created forward-facing.
* "modelAxis"
* "skin" - This is the "on" skin. It may contain materials that make use of the colored keyword or shaderParm7, to change depending on alert state.
* "skin_on_spotlight_off" - This is the "on" skin, but with the spotlight toggled off. This is useful if your model contains inbuilt lightrays that should represent the spotlight.
* "skin_off" - This is the "off" skin. It should not contain materials with the colored keyword or shaderParm7.
* "skin_broken" - When the camera is destroyed it will switch to this skin.

===Misc Spawnargs===

* "start_off" - Whether the camera starts powered on or off.
* "cameraTarget" - Use the view from this entity instead of from self if sending a view to the display screen. See section ''The Display Screen'' for more.
* "gearSpeed" - This spawnarg is set on the ceiling pivot of the 2nd type of security camera. It controls how fast the gears turn when the security camera turns.

The security camera uses spawnargs to place its 'eye' and spotlight in front of the model to ensure the view and spotlight aren't blocked by the model. If you use a different model, you might need to change these.
* "lightOffset"
* "viewOffset"

==Damaging the Camera==

===Damage sources===

By default the security camera is vulnerable only to fire arrows (direct & splash damage). The "damage_" and "damage_mult_" spawnargs allow you to to specify how much damage security cameras take from each weapon, but be sure to communicate the camera's vulnerabilities to the player. You can create your own "damage_mult_" spawnargs by adding the name of a specific weapon classname or damageDef, i.e. "damage_mult_atdm:weapon_shortsword" "0.5". Unfortunately it does not appear to be possible to make water damage the camera, since TDM will crash upon load when a water response is applied to the camera.

Setting "health" to 0 will make the camera totally invicible. Alternatively, you can make the camera immune to everything but fire arrow splash damage by binding a tight-fitting nodrawsolid_metal brush. A similar approach is to bind a brush that leaves parts of the camera exposed, i.e. the lens or face. Note that it will weaken fire arrows considerably if they hit from the wrong angle. A direct hit does up to 400 damage, while the splash does a distance-dependent amount of damage below 100. Note that collision detection is done using the camera's clipmodel, which has a different shape than the visual model.

The player will receive feedback that the camera took damage in the form of spark effects, specified in spawnargs beginning with fx_. An .fx definiton is basically an instruction to emit a sequence of particles and sounds.

===Destroying the Camera===

Security cameras can not only be destroyed, but also be flinderized (burst apart into pieces) which occurs when the security camera takes a hit whose damage is higher than the value of the "damage_flinderize" spawnarg. The "broken" and "skin_broken" spawnargs let you set the model and skin when the camera is destroyed, while the optional "broken_flinderized" and "skin_flinderized" let you set the model and skin when the camera has been flinderized. The "def_flinder" and "flinder_offset" spawnargs allow you to specify the flinder pieces and their spawn point relative to the camera's origin.

==Scripting==

===Script Events===

The security camera supports the following script events:
* getSecurityCameraState() - Returns the security camera's state. 1 = unalerted, 2 = partially alerted, 3 = fully alerted, 4 = inactive (power off), 5 = destroyed, 0 = not a security camera.
* getShaderParm(7) - Returns the current value of shaderParm7 on the camera model. 0 = unalerted, 1 = about to resume sweep after a partial alert, 2 = partially alerted, 3 = fully alerted.
* On() and Off() - Switch the camera's power on or off (note the capitalisation).
* activate() and trigger() - Toggle the camera's power.
* getHealth() and setHealth(float newHealth) - As per the name. Setting health to 0 or lower will destroy the security camera, which is irreversible. setHealth() will make an invincible camera vulnerable.
* setSightThreshold() - This changes how lit up the player's lightgem has to be for the security camera to see him, from 0.0 to 1.0.
* state_light(boolean set) - Switch the camera's spotlight on/off, if the camera has one.
* state_sweep(boolean set) - Switch the camera's sweep on/off. This will also affect enemy tracking.
* state_see_player(boolean set) - Toggle whether the camera is able to detect the player. An alternative is just to set "seePlayer" to "1" or "0", since the code monitors this spawnarg.
* toggle_light() - Toggle the spotlight on/off, if the camera has one.
* toggle_sweep() - Toggle the camera's sweep on/off. This will also affect enemy tracking.
* toggle_see_player() - Toggle whether the camera is able to detect the player. An alternative is just to set "seePlayer" to "1" or "0", since the code monitors this spawnarg.

===Object Functions===

The security camera's scriptobject contains the following object functions:
* toggleSCSpotlight() - calls toggle_light() on the camera if it has a spotlight (spawnarg "spotLight" = "1")
* toggleSCSweep() - calls toggle_sweep() on the camera
* toggleSCPlayer() - calls toggle_see_player() on the camera

As you can see, these object functions simply call the toggle script events on the camera they belong to. This allows you to call the script events from i.e. buttons without scripting. To set this up:
# create an atdm:target_callobjectfunction entity
# give it the spawnarg "call" with the name of the desired object function, i.e. "toggleSCSpotlight"
# let it target the security camera
# when desired, trigger this entity (from a script, from a button etc.).

===Scriptobjects===

The security camera's scriptobject only consists of the 3 object functions mentioned above. Beyond some added utility, this scriptobject has no importance for the security camera and you can easily give it your own scriptobject instead.

===Upon Destruction===

You may call a script when the camera is destroyed, as per the spawnarg "break_up_script". This script should be able to receive the name of the destroyed security camera as input, i.e.:
void camera_destroyed ( entity camera )

An alternative is to use the spawnarg "break_up_target" to name an entity that calls the script when triggered, but this will not pass the name of the destroyed security camera unless you use an atdm:target_callscriptfunction entity with the spawnarg "forEach" "1".

==Sending the camera's view to a Display Screen==

You can create a display screen that shows that the camera sees: all that's needed is a func_static patch that uses a texture like ''textures/common/camera/camera1''. It's recommended to put another patch behind it, since this func_static will get hidden if it's switched off. The screen then needs to be given a spawnarg "cameraTarget" that names either a security camera or a different entity, typically a target_null. The screen will display what that entity sees.

To change the screen's field of view, apply the spawnargs "cameraFovX" and "cameraFovY" to the entity sending the view. Otherwise it will default to "scanFov" for security cameras or 120 for other entities.

The screen is hidden or shown automatically if the screen is displaying a security camera's view. The screen can also be switched on/off manually by triggering it, but this requires the screen to start with the spawnarg "hide" "0" or "hide" "1".

===Multiple Display Screens / Reflective Water / Skybox===

If you plan to have multiple security cameras sending to multiple display screens in your mission, or if the camera display will appear in the same player POV as the sky or reflective water surfaces, you'll need to use unique camera materials for each screen. You can find 9 additional camera materials in the textures/common/camera/ folder. If you should need even more, you can simply clone one of the materials and change the name after the ''map'' keyword.

==Examining a Test Map==

You can obtain a test map with sample cameras in it here: [https://ftp.thedarkmod.com/tutorials/RemoteCamera/camerawiki2.pk4 camerawiki2.pk4]. Similar setups can be found as prefabs in AI/Machines.

Open the map ''camerawiki.map'' in Dark Radiant. In this map, we have examples of the different cameras.

[[Image:Cw1.jpg|256px|thumb|right|cam1]]

'''A rotating camera that sweeps back and forth'''

This camera (''cam1'') starts its rotation at 135 degrees (assuming +X is 0 degrees), and sweeps clockwise until it reaches 45 degrees. It pauses for a moment, then return-sweeps back to 135 degrees. It has a spotlight.

The display for ''cam1'' is on the wall behind it. (Don't worry about the material being displayed backward in the screenshot.)

The display patch uses the material ''camera1'' (provided in the camerawiki/materials/tdm_camera.mtr file).

The four buttons below the display do the following (from left to right):

* Toggle Power - targets ''cam1'' directly. When power is off, the display screen is hidden. You can simulate an "off" screen by making sure there's a black material behind the display. You could also place a glass material behind the display.
* Toggle Spotlight - calls the ''toggleSCSpotlight()'' object function in the camera's scriptobject, turning the spotlight on/off
* Toggle Player Sighting - calls the ''toggleSCPlayer()'' object function in the camera's scriptobject, turning Player detection on/off
* Toggle Sweep - calls the ''toggleSCSweep()'' object function in the camera's scriptobject, turning camera sweep on/off

[[Image:Cw2.jpg|256px|thumb|right|cam1's display]]
{{clear}}
'''A stationary camera that doesn't move'''

[[Image:Cw3.jpg|320px|thumb|right|cam2 and its display]]
This camera (''cam2'') is stationary, w/o a spotlight.

Its display, to its left, uses the material ''camera2''.

The two buttons below the display do the following (from left to right):

* Toggle Power - targets ''cam2'' directly. When power is off, the display screen is hidden.
* Toggle Player Sighting - calls the ''toggleSCPlayer()'' object function in the camera's scriptobject, turning player detection on/off
{{clear}}

'''A screen showing the view from another entity (a target_null)'''

[[Image:Cw6.jpg|320px|thumb|right|a small screen showing what a target_null is seeing]]

This is simply a screen referencing a ''target_null'' as its ''cameraTarget''. The ''target_null'' is in a separate room pointed at a guard.

If you look in the room where the guard is standing, you'll see that the ''target_null'' has the spawnargs ''cameraFovX'' and ''cameraFovY''. These were set because the default field of view for a view from a non-camera entity is 120 by 120, which looks quite zoomed out. For a small screen like this one, 60 by 60 is much better.

Also notice that the screen itself has the spawnarg ''hide'' ''0''. This makes it respond to triggers by hiding or showing itself, allowing you to switch it on or off at the push of a button (see below).

The button below the display does the following:

* Toggle Power - targets the screen directly to show or hide it. This only works because the screen has a ''hide'' spawnarg.

{{clear}}
[[Category:Editing]]