Security Camera: Difference between revisions

From The DarkMod Wiki
Jump to navigationJump to search
mNo edit summary
No edit summary
Line 1: Line 1:
==Security Camera==
==Security Camera==


<span style="color: red">This article documents the security camera as it will be from 2.10 onwards. See [[Security Camera (legacy)]] if you're currently working with TDM 2.09 or older versions.</span>
<span style="color: red">This is the article documenting the security camera of TDM 2.09 and older. See [[Security Camera]] for a more recent version.</span>


The security camera provides the following features:
The security camera (aka remote camera) has been a part of TDM for years, but has been rarely, if ever, used. Recent problems came to light when trying to use it, so I (grayman) decided to flesh it out for 2.06. That done, some issues supporting a more Thief-like camera model were discovered too late in the 2.06 release cycle to safely accommodate required changes in the camera, so work will continue into 2.07.


* It can either sweep back and forth between two angles or remain stationary.
The security camera is different than the cinematic camera discussed in [[Cutscenes]]. The cinematic camera takes over the entire screen and presents to the player what the camera sees. The security camera paints its view on a func_static display provided by the map author.
* If the camera sees the player, it initially plays a short alert sound that is silent to nearby guards. If the player is still in view several seconds later, another alarm sounds. This alarm will play intermittently for a while, even if the player moves out of sight. This second alarm will alert nearby guards.
* 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. Alternatively, the 3 features above 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.


There are different types of cameras:


==The Security Camera: Entities and Prefabs==
* A rotating camera that sweeps back and forth.
* A stationary camera that doesn't move.
* A camera that uses the view from another entity (typically a target_null) to show a scene on its display screen.


Security camera entities can be found in ''AI/Machines/Security Camera'' and inherit from ''func_securitycamera''. Prefabs can be found in ''Mechanical/Machines''.
The camera provides the following features:


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.
* An optional spotlight that points forward, lighting the area in the direction the camera faces. This spotlight can be toggled on/off.
* The ability to toggle the camera power on/off. This is useful if the mapper wants to give the player the ability to shut down power to an area.
* The ability to halt a rotating camera so it stops sweeping. It then becomes equivalent to a stationary camera. Sweeping can be started back up again.
* The camera will normally spot the player, but this can be toggled on/off. When the player is spotted, the camera initially plays a short alert sound. The player is given a short time to hide, but when that time expires and the player is still in view, another alarm sounds. This alarm will play intermittently for a while, even if the player moves out of sight. This second alarm will alert nearby guards.
* If the camera has targets, these will be activated when the second "player alarm" plays. 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.)


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.
==The Security Camera Entity and its Spawnargs==


The camera is ''func_securitycamera'', and it's found in the ''Func'' folder in DR. It comes with a default model, which the map author can change if he wishes.


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


===Movement Spawnargs===
Spawnargs:


* "rotate" - If "1" (default) the camera will rotate. If "0", the camera is stationary.
* "rotate" - If "1" (default) the camera will rotate. If "0", the camera becomes stationary.
* "sweepSpeed" - How many seconds it takes a rotating camera to complete a sweep in one direction.
* "scanDist" - The distance limit for spotting the player, and how far forward the spotlight will travel. Default is 200 units.  
* "sweepAngle" - The angle of sweep. You can cause a camera to initially sweep in the counter-clockwise direction by setting this to a negative number.
* "sweepSpeed" - How many seconds it takes a rotating camera to complete a sweep in one direction. Default is 5 seconds.
* "health" - Cameras can be 'killed'. Default is 100.
* "scanFov" - The camera's FOV. Default is 90 degrees.
* "sweepAngle" - The angle of sweep. Default is 90 degrees. You can cause a camera to initially sweep in the counter-clockwise direction by setting this to a negative number.
* "seePlayer" - If "1" (default) the camera will react if it sees the player. If "0", it won't.
* "sightResume" - How long the camera pauses after losing sight of the player. When this expires, the camera will resume scanning. Default is 1.5 seconds.
* "sightTime" - After spotting the player, the camera will pause this amount of time before it sounds an alarm. Default is 5 seconds. This gives the player some time to hide.
* "sweepWait" - How long the pause is after a sweep completes and starting the return sweep. Default is 0.5 seconds.
* "sweepWait" - How long the pause is after a sweep completes and starting the return sweep. Default is 0.5 seconds.
* "wait" - How long the camera will play its alarm after spotting the player (and deciding it's really the player). Default is 20 seconds. If the player is still visible at the end of this time, the clock will start over again. Otherwise, the camera will pause "sightResume" seconds, then return to scanning.
* "spotLight" - If "1" the camera will start with a spotlight. If you choose not to start with a spotlight, change the camera's skin spawnarg to "security_camera_on_spotlight_off".


Important Spawnargs if you change the camera model:


===Detection Spawnargs===
The default camera uses spawnargs to place its 'eye' and spotlight. If you use a different model, you might need to change these.


* "scanDist" - The distance limit for spotting the player.
* "scanFov" - The camera's field of view.
* "seePlayer" - Whether the camera will react to the player.
* "sightTime" - After seeing the player (partial alert), the camera will wait this amount of time. If it still sees the player, it will sound the alarm. This gives the player some time to hide.
* "sightResume" - If the camera can't see the player anymore after a partial alert, pause for this amount of time. When this expires, the camera will resume sweeping.
* "wait" - How long the camera will stay fully alerted and play the alarm. If the player is still visible at the end of this time, the clock will start over again.
* "alarm_interval" - Amount of time inbetween each activation of the alarm sound, when fully alerted.
===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.
* "spotLight" - If "1" the camera will spawn a spotlight.
* "spotlight_range" - Reach of the spotlight.
* "spotlight_diameter" - Diameter of the spotlight's projection.
* "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 the player = 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 player has disappeared, now waiting "sightResume" seconds before resuming sweeping.
* 2 = partially alerted
* 3 = fully alerted
===Damage Spawnargs===
* "health" - Cameras can be 'killed', including by swords, broadhead arrows and fire arrows, but not blackjacks. You may protect (parts of) the camera from damage with nodrawsolid brushes, but note that fire arrows only do 30 splash damage, equivalent to 1 broadhead hit.
* "fx_damage" - Fx to play whenever the camera is damaged.
* "fx_destroyed" - Fx to play whenever the camera is destroyed.
* "break_up_script" - This script is called when the camera is destroyed.
===Sound Spawnargs===
* "snd_sight" - Sound emitted when the camera notices the player.
* "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_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.
===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, 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.
* "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.
* "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_on" - 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.
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==
By default the security camera is vulnerable to sword attacks, broadhead arrows and fire arrows. The player will receive feedback that a hit was successful in the form of spark effects, specified in "fx_damage" and "fx_destroyed" spawnargs. An .fx definiton is basically an instruction to emit a sequence of particles and sounds.
You can easily make the camera immune to everything but fire arrow splash damage by binding a tight-fitting nodrawsolid_metal brush. Be sure to consider that the camera may be using a separate clipmodel with a different shape. Note that fire arrows only do 30 splash damage throughout a large radius, so you may want to lower the camera's health.
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 the brush.
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.
In any case, be sure to communicate the camera's vulnerabilities to the player.
==Scripting==
===Script Functions===
The security camera supports the following global script functions:
* 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.
* activate() and trigger() - These activate or deactivate the camera fully, representing switching power on or off.
Not supported:
* getHealth() - this only works on AIs and the player.
===Object Functions===


With the correct setup, you can also access object functions from the tdm_security_camera scriptobject:
The "cameraTarget" Spawnarg:
* toggleSCSpotlight() - toggle the spotlight on or off. Sets skin to "skin_on_spotlight_off" if appropriate.
* toggleSCSweep() - toggle the spotlight between sweeping or being stationary.
* toggleSCPlayer() - toggle whether the camera reacts to the player.


The easiest way to call object functions is by triggering atdm:target_callobjectfunction entities. To do so:
For a camera that's displaying its view on a screen, this spawnarg can be left undefined.
# 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.).


For a camera that's replacing its own view with that of another entity (i.e. a target_null), set the following:


===Upon Destruction===
* "cameraTarget" - The name of the entity supplying the view.


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


The display screen where the camera's image is shown is a func_static patch that uses the shader ''textures/darkmod/camera''. Size the patch appropriately.


==Sending to a Display Screen==
Spawnargs:


You can create a display screen: all that's needed is a func_static patch that uses the shader ''textures/darkmod/camera''. 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.
* cameraTarget - The name of the camera whose view will be painted on this display.


Using a security camera has the advantage that you can easily turn the display screen on or off simply by triggering the security camera. If you're using the view from another entity type, switching the screen on/off requires taking advantage of a security camera's coding with the following setup:
If you plan to use more than one camera 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 copy the material shader ''textures/darkmod/camera'' (in materials/tdm_security_camera.mtr) to a map-specific *.mtr file, rename it to something like ''camera1'', and give it a unique ''map'' keyword. Place this file in your mission's ''materials'' folder.
* display_screen with a "cameraTarget" spawnarg pointing to the entity whose view you want
* a security camera with a "cameraTarget" spawnarg pointing to the same entity as above. It doesn't matter where this camera is.
* a button that targets the security camera. Triggering the security camera will toggle the screen display.


For example, if you have two cameras in your mission, you would assign one of these shaders to the display for the first camera, and the other shader to the display for the second:


===Multiple Display Screens / Reflective Water / Skybox===
<pre>
camera1
{
qer_editorimage textures/editor/cameragui.tga
noshadows
{
red Parm0
green Parm1
blue Parm2
remoteRenderMap 232 232 // width / height of render image, ie resolution of screen
  scale -1, -1
translate -1, -1
map "camera1"
}
}


If you plan to use more than one camera with 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.
camera2
{
qer_editorimage textures/editor/cameragui.tga
noshadows
{
red Parm0
green Parm1
blue Parm2
remoteRenderMap 232 232 // width / height of render image, ie resolution of screen
  scale -1, -1
translate -1, -1
map "camera2"
}
}
</pre>


Note the ''map "camera1"'' and ''map "camera2"'' lines. These unique names allow the renderer to correctly display both camera displays in the same mission.


==Examining a Test Map==
==Examining a Test Map==

Revision as of 09:09, 17 February 2021

Security Camera

This is the article documenting the security camera of TDM 2.09 and older. See Security Camera for a more recent version.

The security camera (aka remote camera) has been a part of TDM for years, but has been rarely, if ever, used. Recent problems came to light when trying to use it, so I (grayman) decided to flesh it out for 2.06. That done, some issues supporting a more Thief-like camera model were discovered too late in the 2.06 release cycle to safely accommodate required changes in the camera, so work will continue into 2.07.

The security camera is different than the cinematic camera discussed in Cutscenes. The cinematic camera takes over the entire screen and presents to the player what the camera sees. The security camera paints its view on a func_static display provided by the map author.

There are different types of cameras:

  • A rotating camera that sweeps back and forth.
  • A stationary camera that doesn't move.
  • A camera that uses the view from another entity (typically a target_null) to show a scene on its display screen.

The camera provides the following features:

  • An optional spotlight that points forward, lighting the area in the direction the camera faces. This spotlight can be toggled on/off.
  • The ability to toggle the camera power on/off. This is useful if the mapper wants to give the player the ability to shut down power to an area.
  • The ability to halt a rotating camera so it stops sweeping. It then becomes equivalent to a stationary camera. Sweeping can be started back up again.
  • The camera will normally spot the player, but this can be toggled on/off. When the player is spotted, the camera initially plays a short alert sound. The player is given a short time to hide, but when that time expires and the player is still in view, another alarm sounds. This alarm will play intermittently for a while, even if the player moves out of sight. This second alarm will alert nearby guards.
  • If the camera has targets, these will be activated when the second "player alarm" plays. 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 Security Camera Entity and its Spawnargs

The camera is func_securitycamera, and it's found in the Func folder in DR. It comes with a default model, which the map author can change if he wishes.

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

Spawnargs:

  • "rotate" - If "1" (default) the camera will rotate. If "0", the camera becomes stationary.
  • "scanDist" - The distance limit for spotting the player, and how far forward the spotlight will travel. Default is 200 units.
  • "sweepSpeed" - How many seconds it takes a rotating camera to complete a sweep in one direction. Default is 5 seconds.
  • "health" - Cameras can be 'killed'. Default is 100.
  • "scanFov" - The camera's FOV. Default is 90 degrees.
  • "sweepAngle" - The angle of sweep. Default is 90 degrees. You can cause a camera to initially sweep in the counter-clockwise direction by setting this to a negative number.
  • "seePlayer" - If "1" (default) the camera will react if it sees the player. If "0", it won't.
  • "sightResume" - How long the camera pauses after losing sight of the player. When this expires, the camera will resume scanning. Default is 1.5 seconds.
  • "sightTime" - After spotting the player, the camera will pause this amount of time before it sounds an alarm. Default is 5 seconds. This gives the player some time to hide.
  • "sweepWait" - How long the pause is after a sweep completes and starting the return sweep. Default is 0.5 seconds.
  • "wait" - How long the camera will play its alarm after spotting the player (and deciding it's really the player). Default is 20 seconds. If the player is still visible at the end of this time, the clock will start over again. Otherwise, the camera will pause "sightResume" seconds, then return to scanning.
  • "spotLight" - If "1" the camera will start with a spotlight. If you choose not to start with a spotlight, change the camera's skin spawnarg to "security_camera_on_spotlight_off".

Important Spawnargs if you change the camera model:

The default camera uses spawnargs to place its 'eye' and spotlight. If you use a different model, you might need to change these.

  • "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.

The "cameraTarget" Spawnarg:

For a camera that's displaying its view on a screen, this spawnarg can be left undefined.

For a camera that's replacing its own view with that of another entity (i.e. a target_null), set the following:

  • "cameraTarget" - The name of the entity supplying the view.

The Display Screen

The display screen where the camera's image is shown is a func_static patch that uses the shader textures/darkmod/camera. Size the patch appropriately.

Spawnargs:

  • cameraTarget - The name of the camera whose view will be painted on this display.

If you plan to use more than one camera 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 copy the material shader textures/darkmod/camera (in materials/tdm_security_camera.mtr) to a map-specific *.mtr file, rename it to something like camera1, and give it a unique map keyword. Place this file in your mission's materials folder.

For example, if you have two cameras in your mission, you would assign one of these shaders to the display for the first camera, and the other shader to the display for the second: 

camera1
{
	qer_editorimage textures/editor/cameragui.tga
	noshadows
	{
		red Parm0
		green Parm1
		blue Parm2
		remoteRenderMap 232 232 // width / height of render image, ie resolution of screen
  		scale -1, -1
		translate -1, -1
		map "camera1"
	}
}

camera2
{
	qer_editorimage textures/editor/cameragui.tga
	noshadows
	{
		red Parm0
		green Parm1
		blue Parm2
		remoteRenderMap 232 232 // width / height of render image, ie resolution of screen
  		scale -1, -1
		translate -1, -1
		map "camera2"
	}
}

Note the map "camera1" and map "camera2" lines. These unique names allow the renderer to correctly display both camera displays in the same mission.

Examining a Test Map

You can obtain a test map with sample cameras in it here: camerawiki.pk4.

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

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.)

The display patch uses a custom material camera1 (provided in the camerawiki/materials/camera.mtr file). It's custom because there are other displays in this test map.

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() routine in the camera's scriptobject, turning the spotlight on/off
  • Toggle Player Sighting - calls the toggleSCPlayer() routine in the camera's scriptobject, turning Player detection on/off
  • Toggle Sweep - calls the toggleSCSweep() routine in the camera's scriptobject, turning camera sweep on/off
cam1's display

A stationary camera that doesn't move

cam2 and its display

This camera (cam2) is stationary, w/o a spotlight.

Its display, to its left, uses a custom material camera2 (provided in the camerawiki/materials/camera.mtr file). It's custom because there are other displays in this test map.

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() routine in the camera's scriptobject, turning Player detection on/off


A camera that uses the view from another entity (typically a target_null) to show a scene on its display screen

cam3's display

This camera (cam3) is stationary, w/o a spotlight, and it doesn't spot the player. In the test map, you'll find it in the blue room. Note that the camera uses the following spawnarg:

"cameraTarget" "Cam3View"

If you look in the room where the guard is standing, you'll see a target_null named Cam3View, which provides the view to the display screen.

Look at the other spawnargs on the camera. You'll see that it doesn't rotate, it doesn't have a spotlight, and it won't spot the player.

This camera could be used for something like 'peeking through keyholes', though that functionality hasn't been tested in 2.06. It would most likely need an accompanying 'player ear' in the observed room (not yet implemented). To simulate a keyhole, the display screen would be placed inside the opening. You'd also need a companion camera looking the other way (room->hall).

The button below the display does the following

  • Toggle Power - targets cam3 directly. When power is off, the display screen is hidden.
Retrieved from "https://wiki.thedarkmod.com/index.php?title=Security_Camera&oldid=27271"