Relighting Lights

Overview

Starting with v1.06, TDM supports AI relighting lights. A previous version of TDM supported this in a rudimentary way, but interim versions lost that capability.

In general, the human AI in TDM notice when a light that's been on suddenly goes out. They might simply comment on this, or they might try to relight the light. The mapper has control over which lights can be relit, which arouse suspicion when they've gone out, and which can be ignored. This gives the mapper another tool to enhance the atmosphere of their map.

The code for this was kindly contributed by grayman.

AI Spawnargs

Most lights in TDM can be relit if they go out. However, it's not in the player's interest if every wall torch they douse with a water arrow gets relit a moment later by a passing AI. For the player's benefit, TDM uses AI spawnargs to control relight behavior.

• chanceNoticeLight: The probability that an AI will comment that a light has gone out. (From 0.0 to 1.0)
• canLightTorches: Whether an AI can relight doused flames. (1 = yes, 0 = no)
• canOperateSwitchLights: Whether an AI can turn on electric lights that have gone out. (1 = yes, 0 = no)
• chanceLightTorches: Once an AI has passed the chanceNoticeLight check, this is the probability that he'll try to relight a doused flame. (From 0.0 to 1.0)
• chanceOperateSwitchLights: Once an AI has passed the chanceNoticeLight check, this is the probability that he'll try to turn on an electric light that has gone out. (From 0.0 to 1.0)

The default settings for these spawnargs on human AI are:

chanceNoticeLight 0.9

canLightTorches 1

canOperateSwitchLights 1

chanceLightTorches 0.4

chanceOperateSwitchLights 0.7

In all cases but one, if an AI fails to make a relight attempt, he'll ignore the light for at least 15 seconds. The exception is when he doesn't have a direct line of sight to the light. See the Line of Sight section below.

Certain AI override these defaults. For example, revenants and zombies couldn't care less when lights go out, so their chanceNoticeLight spawnarg is set to 0.

When you add an AI to your map, override these defaults as needed to change the AI's relight behavior.

Light Spawnargs

Lights use these spawnargs to define how they're treated by the AI:

• shouldBeOn: Controls AI response to a light going out. (0, 1, or 2. See description below.)
• AIUse: Set to AIUSE_LIGHTSOURCE for light sources.
• lightType: Set to AIUSE_LIGHTTYPE_TORCH for flames or AIUSE_LIGHTTYPE_ELECTRIC for electric lights.

The default settings for these spawnargs are:

shouldBeOn 0

AIUse AIUSE_LIGHTSOURCE

lightType AIUSE_LIGHTTYPE_TORCH (for flames)

lightType AIUSE_LIGHTTYPE_ELECTRIC (for electrics)

shouldBeOn

A light's shouldBeOn spawnarg defines how AI will respond to its going out.

• 0 - Comment that the light has gone out, but don't relight it.
• 1 - Comment that the light has gone out, and try to relight it. If discovered w/in 10 seconds of when it went out, increase suspicion that an intruder might be present.
• 2 - Comment that the light has gone out, and try to relight it. Increase suspicion that an intruder might be present.

shouldBeOn can be set on light holders. For example, a candle is a candle flame entity bound to a candle model. The candle entity is what you place in your map, and since you can't directly change the shouldBeOn spawnarg on the flame, you need to set it on the candle. This is true for all compound entities that spawn lights, from candles to fireplaces.

If you want AI to completely ignore a light (not even comment when it goes out), put the following spawnarg on it:

 "AIUSE" " "

If it has a def_attached flame, you also need to add the following

 "set AIUSE on flame" " "

Light Switches

Some lights, for example the desk lamp, are turned on/off by frobbing them directly. For lights that have a switch, AI will use the switch. If more than one switch can turn a light on/off, AI will use the nearest. Though AI need a direct line of sight to the light to notice that it's out, they don't need a direct line of sight to a switch. The switch can be behind a door, around a corner, or even on a different floor. Wherever it is, if AI can walk to it, they'll use it.

If there are difficulties, try adding the relight-position discussed below. Beyond that, for wall switches, sometimes the AI will try to get to the backside of the switch to (unsuccessfully) relight it. This can happen if the switch origin is buried in a worldspawn wall. Either make the wall func_static or move the switch origin out of the worldspawn.

Height of Light

When a light is high off the floor (or ground), AI reach up to perform the relight. For the animation to look as real as possible, don't place relightable lights more than 100 off the floor. AI will not try to relight lights higher than that. The same applies to switches: a switch more than 100 off the floor won't be used.

Relight Position

If you find that relight positions determined by TDM aren't working--perhaps you have a complex light design--you can use a relight_position entity (darkmod/Lights/atdm:relight_position).

Place this at the spot where you want the AI to stand when relighting. One requirement is that its horizontal distance from the light be no more than 68. Link it to the light by adding a target spawnarg on the light, with its value set to the name of the relight_position. You can define multiple relight positions (target1, target2, etc.) and TDM will select the one that's nearest to the AI at relight time.

You can't assign a relight_position to a movable light, for example a candle. If you pick the light up, or knock it over, the relight position won't change. Because of this, TDM will ignore all relight_positions targeted by the light, and will instead determine a relight standing position based on where the movable light currently is.

Line of Sight

If an AI doesn't have direct line of sight (LOS) to a light that's out, he won't apply the "wait 15 seconds" rule. This lets him comment on a light the moment he establishes LOS, and it also lets him deal with situations where--because of the AI's orientation to the light--something surrounding it is momentarily blocking LOS. For example, LOS to a flame entity inside the basket of a gothic wall torch might hit a basket tine on one attempt (fail), and pass between tines the next (pass). Moving the light entity slightly (especially up) should increase the odds of establishing LOS in these cases.

Unreachable Lights

When a light can't be reached to be turned back on, we don't want patrolling AI to incessantly comment on the light being out. Over time, the number of comments will dwindle, then stop.

AI Don't Need a Torch

An AI that isn't carrying a torch can still relight doused flames. New animations allow him to pull a tinderbox from his belt to get the job done.

Electric Lights

If you construct an electric light using the basic light entity (light) and an electric light model, the AI won't try to relight it if it goes out. This may or may not change in a future rev.

If you want AI to notice that an electric light has gone out, use one of the electric light entities in darkmod/Lights/Switchable/Electric/Flickering/. These entities use both lit and unlit model skins to match the light state, which makes them preferable to roll-your-own electric lights.

See also

• Electric Lights
• Light Properties