L4D2 Director Scripts

From Valve Developer Community
Jump to: navigation, search
简体中文

<Squirrel Language><Left 4 Dead 2> Left 4 Dead 2 Director scripts are vscripts that are primarily used to influence the behavior of the AI Director. They are extensively used for custom finales and gauntlet events.

Usage

Director scripts typically contain a table named DirectorOptions, which contains variables that change up the decision making of the Director. They can be ran / stopped with the following inputs to the info_director entity:

BeginScript <string>
Run a Director script, and parse its DirectorOptions table once. If a Director script is already running and this input is called, the previous Director script automatically stops running.
EndScript
Ends the running script and resets the Director options to either the map's DirectorOption values, or the default settings.
ScriptedPanicEvent <string>
With the script name given it'll be ran as a Scripted Panic Event, which is like a mini finale, so the script should be structured as a finale script.
Note.png Note: Scripts used with ScriptedPanicEvent will not work if they are in a subdirectory under thevscriptsfolder, even though you can use subdirectories in other script contexts. If they don't reside under the vscripts folder, they will simply act as a 1 stage 1 second delay Panic Event.

There is too, a CDirector object for VScripts, which its extra functions can be paired for customizing your Director scripts.

General scripts and Onslaughts

Scripts launched with the BeginScript Director input run until a different script is launched, or the script is manually ended with the EndScript input. Unless new Director Options are set, the gameplay continues on as normally.

Onslaught events are created by manipulating the pacing and spawn limits of mobs and special infected.

c2m4_barns_onslaught.nut (with annotations):

Msg("Initiating Onslaught\n");

DirectorOptions <-
{
	// This turns off tanks and witches (when true).
	ProhibitBosses = false
	
	//LockTempo = true

	// Sets the time between mob spawns. Mobs can only spawn when the pacing is in the BUILD_UP state.
	MobSpawnMinTime = 1
	MobSpawnMaxTime = 1

	// How many zombies are in each mob.
	MobMinSize = 30
	MobMaxSize = 30
	MobMaxPending = 30

	// Modifies the length of the SUSTAIN_PEAK and RELAX states to shorten the time between mob spawns.
	SustainPeakMinTime = 5
	SustainPeakMaxTime = 10
	IntensityRelaxThreshold = 0.99
	RelaxMinInterval = 1
	RelaxMaxInterval = 5
	RelaxMaxFlowTravel = 50

	//Special infected options
	SpecialRespawnInterval = 1.0
        SmokerLimit = 2
        JockeyLimit = 0
        BoomerLimit = 0
        HunterLimit = 2
        ChargerLimit = 1

	// Valid spawn locations
	PreferredMobDirection = SPAWN_NO_PREFERENCE
	ZombieSpawnRange = 2000
}

Director.ResetMobTimer()		// Sets the mob spawn timer to 0.
Director.PlayMegaMobWarningSounds()	// Plays the incoming mob sound effect.


Finales and Scripted Panic Events

Finales with the 'custom' type, and Scripted Panic Events (or minifinales), both make use of a script to setup the structure of the event. In the script, it consists of stages defined inDirectorOptions.

The finale's Director Script is always loaded as the<map name>_finale.nutname. On the other hand, Scripted panic events are initiated from theinfo_directorScriptedPanicEventinput.

Bug.png Bug: trigger_finalehas an option to specify a script, but it is non-functional.

Setting up stages

A stage can be one of 4 types (other values will break the finale and go right to ESCAPE):

Name Value Description
PANIC 0 A panic event; The value is the number of infected waves.
TANK 1 Spawn tank(s), with the value as the number of tanks to spawn.
DELAY 2 A delay, its value is the number of seconds to wait before it goes to the next stage.
SCRIPTED 3 Also under theONSLAUGHTname, sets up a wave based on the loaded script'sDirectorOptionssettings. The value should be a string containing the name of the VScript you want to call, without the file extension.

If you use theSCRIPTEDstage, yourSCRIPTEDstage's script is responsible for sending anEndCustomScriptedStageinput to the Director, otherwise it will last forever. Ideally, a goal of your choice is used to send the input, like a certain trigger volume or a timer.

For finales, two alternatives are available: Thetrigger_finaleinputAdvanceFinaleState, and theMinimumStageTime key for DirectorOptions.

Bug.png Bug: In Scripted Panic Events, sending anEndCustomScriptedStageinput ends the event immediately.
Bug.png Bug: In Scripted Panic Events, when the last stage ends, it will repeat itself once more, but with the lowest valid value (if applicable). The effects of this are as follows:

Code Sample

An example custom finale script, that also makes use of various finale settings documented at later parts of this page:

const ERROR = -1
const PANIC = 0
const TANK = 1
const DELAY = 2
const SCRIPTED = 3 

DirectorOptions <-
{
	//-----------------------------------------------------
	A_CustomFinale_StageCount = 3 // Number of stages. Used for calculating the Versus score.
	B_CustomFinale_StageCount = 3 // Number of stages for the alternate B finale type
	
	A_CustomFinale1 = PANIC
	A_CustomFinaleValue1 = 2	// Two panic waves.
	
	A_CustomFinale2 = DELAY
	A_CustomFinaleValue2 = 5 	// Delay for five seconds in addition to stage delay.
	
	A_CustomFinale3 = TANK
	A_CustomFinaleValue3 = 3 	// 3 tanks! Start rescue for Finale Type A after this wave ends too.
	
	B_CustomFinale1 = SCRIPTED
	B_CustomFinaleValue1 = "my_scripted_stage"	// Start of with running a custom scripted stage using a separate script.
	
	B_CustomFinale2 = TANK
	B_CustomFinaleValue2 = 1 	// Follow up with a single tank.

	B_CustomFinale3 = DELAY
	B_CustomFinaleValue3 = 5	// Wait five more seconds ... rescue for Finale Type B!

	//-----------------------------------------------------

	CommonLimit = 10
	SpecialRespawnInterval = 25
}

function OnBeginCustomFinaleStage( num, type ) // This function is run at the beginning of every stage.
{
	printl( "Beginning custom finale stage #" + num + " of type: " + type )
	if( DirectorOptions.CommonLimit < 30 )
		DirectorOptions.CommonLimit = num * 5 // Increase commons by 5 linearly with stages.
}

Adaptive Dramatic Pacing

To do: Add info from [1]


Callbacks

  • float GetCustomScriptedStageProgress(float defvalue)
Will be called during FINALE_CUSTOM_SCRIPTED stages. The function should return a value from 0-1 to indicate the completion percentage of the stage. The default time-based completion percentage is passed in as a parameter.
  • void OnBeginCustomFinaleStage(int num, int type)
If defined, will be called on every stage change with the number, and type, this is how you would change director options between stages (spawn directions, etc). num refers to the finale stage number passed by the director and type is the stage type (PANIC, TANK, etc.).
Bug.png Bug: The CEntities object will not work properly in this callback, always returning the default value null every tick until Squirrel terminates the script.
  • function OnChangeFinaleMusic()
To do: confirm category/working
  • function OnChangeFinaleStage(?)
To do: confirm category/working

DirectorOptions

TheDirectorOptionstable is used for overriding various Director variables that govern among other things: infected spawning rough distance, finale stages, and others.

In mode and map scripts, use SessionOptions and MutationOptions/MapOptions! SessionOptions for influencing the director, while the MutationOptions/MapOptions tables for setting default values. This is because the normal DirectorOptions table can conflict with other scripts, especially on a finale event, as custom finales are often and require DirectorOptions.

Note.png Note: 'Mode scripts' term refer to scripts ran when a specific gamemode is active, likeshootzones.nutorc3m1_plankcountry_holdout.nut. 'Map scripts' on the other hand, are ran anytime during a map, dependent of map logic. Examples for this include:c9m1_alleys_minifinale.nutandc11m4_reserved_wanderers.nut.

Though, while customizing the Director's behaviour, you might come across these issues:

The Fields interact a lot!
Say you have a custom mutation mod, and you use aDirectorOptionstable to influence the Director. It reducesCommonLimit for lesser Commons, but also reduces bothMobSpawnTimeMinandMobSpawnTimeMax to make them respawn faster. However, when playtesting your mod on Dead Center, everything seems to revert to default after you complete the Gauntlet fetch quest, featuring weapon_cola_bottles. While not a great example scenario, this is to show something that can happen if you're not careful: Things working not as expected, as DirectorOptions have been set in ways that conflict, causing unexpected behaviors.

When you see odd behavior like this, think about what other variables and objects might be interfering with your plans. Going back to the earlier example, the cause of this could be other scripts using aDirectorOptionstable, so if you remember, you could try aMutationOptionstable and see if it works. But if it doesn't, its okay, because if you inspect the keys documentation below, you'll find out the keycm_CommonLimitalso exists, and could solve your other problems. Viewing the list of usableDirectorOptionskeys can be very vital when debugging issues like these, sometimes you find something that just does what exactly you want.

Don't forget to use the proper assignment operator!
With a new DirectorOptions table, you should use the<-operator. <- is required over using thelocaltag and the= operator, as variables created with<-become globals, allowing the C++ side of the game to use DirectorOptions.

Note.png Note: The default values are for reference of the values set elsewhere in-game (if it has one), and do NOT mean that the DirectorOption key is set by default. Blank values for a key also imply something simply has no default value.


General

Name Type Default value Description
AddToSpawnTimer float
AllowCrescendoEvents bool true
AllowWitchesInCheckpoints bool false Whether Witches are allowed to access nav areas marked with CHECKPOINT.
AlwaysAllowWanderers bool
BuildUpMinInterval int
ClearedWandererRespawnChance int 0; 3 in Scavenge Percent chance (0-100) that cleared nav areas will get re-populated with wanderers.
DisallowThreatType int Disallows boss types from being spawned in threat areas in coop mode. Valid flags are:ZOMBIE_WITCH, ZOMBIE_TANK
FarAcquireRange float 2500.0 The maximum range common infected can spot survivors.
NearAcquireRange float 200.0 The range where common infected can spot survivors in the least amount of time.
FarAcquireTime float 5.0 The time it takes for an infected to acquire the survivor after spotting them at maximum range.
NearAcquireTime float 0.5 The time it takes for an infected to acquire the survivor after spotting them at minimum range.
GasCansOnBacks bool false Puts the Hard Rain diesel cans on the survivors backs.
GetSpecialSlotCountdownTime float
IgnoreNavThreatAreas bool false Likely prevents bosses from spawning along the nav.
Confirm:In proper category, and still working? Used in dash
InfectedFlags int 0 Applies flags to newly spawned infected. Valid flags are: INFECTED_FLAG_CANT_SEE_SURVIVORS, INFECTED_FLAG_CANT_HEAR_SURVIVORS, INFECTED_FLAG_CANT_FEEL_SURVIVORS
IntensityRelaxAllowWanderersThreshold float 0.8 in Expert; 0.5 in Advanced; 0.3 in other difficulties If the maximum intensity of the survivors is below this threshold, wandering commons can spawn.
IntensityRelaxThreshold float 0.9 All survivors must be below this intensity before a Peak is allowed to switch to Relax (in addition to the normal peak timer)
JournalString string -none- To do: Used in holdout, seems to build some kind of table. Is this for the Director Journal related I/O inputs?
LockTempo bool false Locks the horde spawning to only be at the COMBAT phase.
Note.png Note: The horde spawning pacing consists of: BUILD_UP -> spawn horde -> SUSTAIN_PEAK -> RELAX -> BUILD_UP again. SettingLockTempo = trueremoves the "SUSTAIN_PEAK -> RELAX -> BUILD_UP" bit making your hordes spawn constantly without a delay.
MobRechargeRate float 0.0025 How fast a mob's CI spawn in-between each other.
MobSpawnMaxTime float 180.0-240.0 Maximum time in seconds between mob spawns. Default value depends on difficulty.
MobSpawnMinTime float 90.0-120.0 Minimum time in seconds between mob spawns. Default value depends on difficulty.
MusicDynamicMobScanStopSize int 3 When fewer than this many of a mob are in play, the mob music stops.
MusicDynamicMobSpawnSize int 25 Spawning a mob this large will play the mob music.
MusicDynamicMobStopSize int 8 When a mob gets to this size, the Director thinks about stopping the mob music.
NumReservedWanderers int 0 The number of wandering infected that cannot be despawned for mobs.
NoMobSpawns bool false Prevents new mobs from spawning. Does not reset the timer, and already pending infected still spawn.
PanicForever bool false This seems to only work in gauntlets.
PausePanicWhenRelaxing bool false
Confirm:In proper category, and still working? Used in dash
PreferredMobDirection int -1 Valid flags are: SPAWN_ABOVE_SURVIVORS, SPAWN_ANYWHERE, SPAWN_BEHIND_SURVIVORS, SPAWN_FAR_AWAY_FROM_SURVIVORS, SPAWN_IN_FRONT_OF_SURVIVORS, SPAWN_LARGE_VOLUME, SPAWN_NEAR_IT_VICTIM, SPAWN_NO_PREFERENCE
Note.png Note: SPAWN_NEAR_IT_VICTIM does not exist before a finale and will cause an error, so I'm assuming the director picks someone as IT when the finale starts.[confirm]
Note.png Note: SPAWN_LARGE_VOLUMEis what makes infected be a considerable distance away, like on Dead Center finale.
To do: Explain more, and do it on a new page forPreferredMobDirection
PreferredMobPosition Vector -none-
Confirm:In proper category, and still working? Used in dash
PreferredMobPositionRange float -none-
Confirm:In proper category, and still working? Used in dash
PreferredSpecialDirection int -1
Note.png Note: The same values for PreferredMobDirection appear to work, BUT the following have also been seen, it is unknown if it's just redundancy. SPAWN_SPECIALS_ANYWHERE, SPAWN_SPECIALS_IN_FRONT_OF_SURVIVORS
ProhibitBosses bool false Prohibits tanks and witches from being spawned by the Director. Campaign modes only.
RelaxMaxFlowTravel float 3000 How far the survivors can advance along the flow before transitioning from RELAX to BUILD_UP.
RelaxMaxInterval float 45 Maximum seconds to spend in the RELAX tempo.
RelaxMinInterval float 30 Minimum seconds to spend in the RELAX tempo.
ShouldAllowMobsWithTank bool false Whether to allow spawning of infected mobs (except Boomer / Bile Bomb spawned mobs) when a tank is in play. Campaign modes only.
ShouldAllowSpecialsWithTank bool false Whether to allow spawning of Special Infected when a tank is in play. Campaign modes only.
ShouldConstrainLargeVolumeSpawn bool true IfSPAWN_LARGE_VOLUMEis used, it'll obey the restrictions imposed by the convarsz_large_volume_mob_too_far_xyandz_large_volume_mob_too_far_z.
To do: Move to new page with images
ShouldIgnoreClearStateForSpawn bool false
Confirm:In proper category, and still working? Used in dash
SpawnBehindSurvivorsDistance float Appears to require PreferredSpecialDirection = SPAWN_BEHIND_SURVIVORS
SpecialInfectedAssault bool false To do: confirm category/working
SpecialInitialSpawnDelayMax float 60.0 Specials cannot spawn for this many time maximum after the survivors exited the saferoom. Campaign modes only.
SpecialInitialSpawnDelayMin float 30.0 Specials cannot spawn for this many time minimum after the survivors exited the saferoom. Campaign modes only.
SpecialRespawnInterval float 45 in Campaign, 20 in Versus Time in seconds before a Special Infected slot can respawn an infected.
SurvivorMaxIncapacitatedCount int 2 Maximum amount of survivor incapacitating before dying.
SustainPeakMaxTime float 5 in minutes[confirm]
SustainPeakMinTime float 3 in minutes[confirm]
TankHitDamageModifierCoop float 1.0 Damage dealt by Tanks is multiplied by this number in Campaign modes.
TankRunSpawnDelay float 15 in seconds (mutation19.nut Taaannnkk!)
Confirm:In proper category, and still working? Used in dash
TempHealthDecayRate float 0.27 0.27 is the pain_pills_decay_rate default, higher values equals quicker decay.
WanderingZombieDensityModifier float 1.0 Multiplier for the amount of wandering infected.
WaterSlowsMovement bool true Slows movement when in water.
ZombieDiscardRange int 2500 Any CI beyond this point will be deleted, while any AI-controlled SI will suicide.
ZombieDontClear bool false Do not mark nav areas as cleared.
ZombieSpawnInFog bool false Allows zombies to spawn in in line-of-sight of survivors in fogged areas.
ZombieSpawnRange float 1500.0 Maximum distance from the survivors that the infected can spawn.
ZombieTankHealth float 4000.0 Sets the amount of health a tank spawns with. The health is later affected by hidden health modifiers:

Spawning limits

Name Type Default value Description
BileMobSize int Number of commons that spawn when a bile bomb is thrown or a survivor is hit by vomit. Only works if scripted mode is enabled, a custom finale is active, or a scavenge finale is active. Found in Dead Center and The Sacrifice finales.
Confirm:Re-verify, the described conditions seem too specific
BoomerLimit int 1 Maximum number of Boomers allowed to be in play simultaneously.
ChargerLimit int 1 Maximum number of chargers allowed to be in play simultaneously.
CommonLimit int 30 Maximum number of commons allowed to be in play simultaneously.
DominatorLimit int -none- Maximum number of Hunters, Smokers, Jockeys and Chargers allowed to be in play simultaneously.
HunterLimit int 1 Maximum number of Hunters allowed to be in play simultaneously.
JockeyLimit int 1 Maximum number of Jockeys allowed to be in play simultaneously.
MaxSpecials int 2 Maximum number of Director spawned Special Infected allowed to be in play simultaneously.
MegaMobSize int 50 The amount of total infected spawned during a panic event.
MobMaxPending int -1 How many infected can be left pending to spawn when the mob size is larger than CommonLimit.
MobMaxSize int 30 Maximum amount of infected that can spawn in a mob.
MobMinSize int 10 Minimum amount of infected that can spawn in a mob.
MobSpawnSize int -none- Static amount of infected in a mob. Likely overrides MobMinSize and MobMinSize.
PreTankMobMax int 50
Confirm:In proper category, and still working? Possibly Gauntlet finale specific?
SmokerLimit bool 1 Maximum number of Smokers allowed to be in play simultaneously.
SpitterLimit int 1 Maximum number of Spitters allowed to be in play simultaneously.
TankLimit int -1 Maximum number of Tanks allowed to be in play simultaneously.
WitchLimit int -1 Maximum number of Witches allowed to be in play simultaneously. Less than 0 means no maximum.

EMS Stage Specific

To do

See L4D2_EMS/Appendix:_Spawning_Infected


Name Type Default value Description
PanicSpecialsOnly bool false The Panic should end when we finish with Specials, not wait for the MegaMob.
PanicWavePauseMax float To do: confirm category/working
PanicWavePauseMin float To do: confirm category/working
ScriptedStageType int 9 The type of stage to run next. See L4D2_EMS/StageTypeAppendix for a description of stage types.
ScriptedStageValue int 1 Dependant on the stage type.
SpawnDirectionCount int 0 To do: confirm category/working
SpawnDirectionMask int 0 A bitfield (using SPAWNDIR_N, _NE, _E, etc) of directors to spawn from _relative to_ a map entity named Compass in your map. Designed for Survival-like game modes. See L4D2_EMS/Appendix:_Spawning_Infected.
SpawnSetPosition Vector The center point of the area infected can spawn in, when SpawnSetRule is set to SPAWN_POSITIONAL.
SpawnSetRadius float 1000.0 How far from the center point infected can spawn, when SpawnSetRule is set to SPAWN_POSITIONAL.
SpawnSetRule int 0 Overrides the mode of spawning used. Seems to be non-functional in finales. Valid flags are: SPAWN_ANYWHERE, SPAWN_FINALE, SPAWN_BATTLEFIELD, SPAWN_SURVIVORS, SPAWN_POSITIONAL
TotalBoomers int 0 Number of Boomers allowed in a wave.
TotalChargers int 0 Number of Chargers allowed in a wave.
TotalHunters int 0 Number of Hunters allowed in a wave.
TotalJockeys int 0 Number of Jockeys allowed in a wave.
TotalSmokers int 0 Number of Smokers allowed in a wave.
TotalSpecials int 0 Total number of Special Infected allowed in a wave.
TotalSpitters int Number of Spitters allowed in a wave.
  • function void g_ModeScript::GetNextStage()
Called by the director when it wants a new stage. It can be forced with Director.ForceNextStage()

Finale Specific/Related

A normal finale consists of X number of stages. Some variables in DirectorOptions can only be used during finales. Multiple staged events can be defined in the same script, with the Options starting with A_, B_, C_ etc.

Name Type Default value Description
[A-Z]_CustomFinale_StageCount int -none- Number of stages. Needs to be set for Versus scoring to function properly.
[A-Z]_CustomFinaleX int -none- Stage type (enumerated PANIC, SCRIPTED (AKA ONSLAUGHT), DELAY, TANK), where X is the corresponding stage number. Usable in scripted panic events.
[A-Z]_CustomFinaleValueX any -none- Value depends on the stage type above. Usable in scripted panic events.
[A-Z]_CustomFinaleMusicX string -none- Soundscript entry to play. For instance, A_CustomFinaleMusic1 = "C2M5.BadManTank2" will play a Dark Carnival - Concert finale song. Does not work in Scripted Panic Events.
Note.png Note: Dark Carnival - Concert finale does not use this method! It instead uses map logic and ambient_music. However its finale script hasA_CustomFinaleMusic4= "", suggesting that it may be disabling the default Tank music.
EnforceFinaleNavSpawnRules bool true Possibly used to enforce the finale spawning behavior without running a finale. To do: confirm category/working
HordeEscapeCommonLimit int -1 Number of commons allowed in the escape stage.
EscapeSpawnTanks bool true Whether to spawn tanks in the escape sequence. To do: possibly EMS stage related
MinimumStageTime float 1.0 The minimum amount of time a SCRIPTED stage is allowed to run before ending. Unavailable for Scripted Panic Events.

Gauntlet Specific/Related

These options are specific to Gauntlet finales. Most of these can be found in director_gauntlet.nut

Name Type Default value Description
CustomTankKiteDistance float 3000.0 Controls when the Gauntlet's Tank wave should start if a survivor advanced this far, in flow distance.


Movement Bonus related options
Movement Bonus are an unique RELAX pacing method present only in Gauntlet finales. Everytime the Movement Timer finishes its timing, Movement Bonus is incremented by its set value. However if a new mob spawns, the Director initiates an extra variable afterwards: Current Bonus. Current Bonus is a timer that lasts as long as the current Movement Bonus, which when still ticking down, disallows the Director from spawning any new infecteds (except Tanks).

To familiarize with Movement Bonus better, usedirector_debug 1in-game to see the values.

Name Type Default value Description
GauntletMovementThreshold float 500.0 When survivors advance this many amount of flow distance, from the last reset point or the start point, Movement Bonus, Movement Timer and Current Bonus is reset to defaults.
GauntletMovementTimerLength float 5.0 The interval between each Movement Bonus increase, in seconds.
GauntletMovementBonus float 2.0 The initial value, and the amount the movement Bonus increases everytime the timer stops, in seconds.
GauntletMovementBonusMax float 30.0 The maximum value that the Movement Bonus can store.

Versus Specific

Name Type Default value Description
TankHitDamageModifierVersus float 1.0 Damage dealt by Tanks is multiplied by this number in Versus modes.
ZombieGhostDelayMax float 30.0 Maximum time in seconds until allowing player infected to respawn.
ZombieGhostDelayMin float 20.0 Minimum time in seconds until allowing player infected to respawn.


Scavenge Specific/Related

Name Type Default value Description
ScavengeClusterBonusTime float To do: confirm category/working
ScavengeRoundInitialTime float 90.0 The timer's initial length when the round starts.
ScavengeScoreBonusTime float 15.0 Amount of time added to the timer when a gascan is successfully poured.

Survival Specific/Related

Name Type Default value Description
SurvivalSetupTime float (Used in mutation15.nut for Survival Versus with setup time of 90 seconds)


Mutation Specific/Related

Some of these values are mutation specific values of the global ones (cm_CommonLimit,cm_MaxSpecials, etc.), so use them if you are making a mutation, in case any map scripts are changing the global values.

Name Type Default value Description
cm_AggressiveSpecials bool false
cm_AllowPillConversion bool true Allows pills to be converted to health kits.
cm_AllowSurvivorRescue bool
cm_AllowTeamSwap bool true Allows swapping teams.
Note.png Note: Appears to be non-functional.
cm_AutoReviveFromSpecialIncap bool false Instantly revives a survivor when incapacitated by a Special Infected.
Bug.png Bug: Doesn't work if a player isn't incapacitated by being dominated.
cm_AutoSpawnInfectedGhosts bool false
cm_BaseCommonAttackDamage float
cm_BaseSpecialLimit int Controls the default max limits of all the Special Infecteds.
cm_CommonLimit int Identical to theCommonLimit key, except this key will be priortized over anyCommonLimitkeys.
cm_DominatorLimit int Identical to theDominatorLimit key, except this key will be priortized over anyDominatorLimitkeys.
cm_FirstManOut bool false Ends the escape when the first survivor reaches the escape vehicle.
cm_frustrationTimer
cm_HeadshotOnly bool false Every infected only takes damage when shot to the head, else they will only stumble. Tanks are excepted from this.
cm_HealingGnome bool false All survivors start with only temporary health, with a gnome to be picked up near of them; The gnome will slowly regenerate the health of anyone who holds it.
cm_InfiniteFuel bool false (mutation7.nut Chainsaw Massacre)
cm_MaxSpecials int -none- Identical to theMaxSpecials key, except this key will be priortized over anyMaxSpecialskeys.
cm_NoRescueClosets bool false
cm_NoSurvivorBots bool false Should survivor bots be kicked on round start?
cm_ProhibitBosses bool -none- Identical to theProhibitBosses key, except this key will be priortized over anyProhibitBosseskeys.
cm_ShouldEscortHumanPlayers bool
cm_ShouldHurry bool false
cm_SingleScavengeCluster bool false Only a group of scavenge cans together will be active at once.
cm_SpecialRespawnInterval int -none- Identical to theSpecialRespawnInterval key, except this key will be priortized over anySpecialRespawnIntervalkeys.
cm_SpecialSlotCountdownTime
cm_SpecialsRetreatToCover bool 0
cm_TankLimit int -none- Identical to theTankLimit key, except this key will be priortized over anyTankLimitkeys.
cm_TankRun bool false Used in Taaank! mutation (mutation19.nut).
cm_TempHealthOnly bool false
cm_VIPTarget bool false
cm_WanderingZombieDensityModifier int -none- Identical to theWanderingZombieDensityModifier key, except this key will be priortized over anyWanderingZombieDensityModifierkeys.
cm_WitchLimit int -none- Identical to theWitchLimit key, except this key will be priortized over anyWitchLimitkeys.

Defunct options

These don't seem to be read by the director.

Name Type Default value Description
ActiveChallenge bool false Activates mutation mode. Seems to be obsolete with the EMS update.
MegaMobMaxSize int Maximum amount of total infected spawned during a panic event. Doesn't work 2014.04.29
MegaMobMinSize int Minimum amount of total infected spawned during a panic event. Doesn't work 2014.04.29


Callback Functions

When functions with these specific names are placed in the DirectorOptions table, they get called by C++ with specific arguments used. Only called at the start of every round.

Function Signature Description
AllowFallenSurvivorItem bool AllowFallenSurvivorItem(string classname) For the given weapon classnames, return true to allow Fallen Survivors to carry the item, false / none is otherwise.
AllowWeaponSpawn bool AllowWeaponSpawn(string classname) Return false to the given string to disallow the respective weapon from spawning, used by several mutations.
ConvertWeaponSpawn string ConvertWeaponSpawn(string classname) For the given weapon classname, return another classname to convert the weapon to another, used by several mutations.
ConvertZombieClass int ConvertZombieClass(int infectedClass) Converts player-controlled Special Unfecteds into another. Used by the Taaannnk!! mutation (mutation19.nut).
GetDefaultItem string GetDefaultItem(int index) Repeatedly called with incrementing indices. Return a string of a weapon name to make it a default item for survivors, or 0 to end the iteration.
ShouldAvoidItem bool ShouldAvoidItem(string classname) Return true or false to the given weapon classname to either make bots dislike or prefer a weapon. Used in mutations such as Four Swordsmen (mutation5.nut) or Chainsaw Massacre (mutation7.nut).
ShouldPlayBossMusic bool ShouldPlayBossMusic(int index) Returns true or false if the music index is allowed to play.

Enumerations

Dump of Enumerations fromDirectorScript table. If you have a script that intends to access these, but won't be ran with the info_director's inputs, access the enums like this manner to avoid errors:DirectorScript.ALLOW_BASH_ALL.

Some enums here are bitmasked (these:1 << 2), so they can be combined with other ones. Any hook / callback functions are stylized as italics.

AllowBash

  • ALLOW_BASH_ALL = 0
  • ALLOW_BASH_PUSHONLY = 1
  • ALLOW_BASH_NONE = 2

CTerrorPlayer::GetSenseFlags, CTerrorPlayer::SetSenseFlags (Bitmasks)

  • BOT_CANT_SEE = 1
  • BOT_CANT_HEAR = 2
  • BOT_CANT_FEEL = 4

CommandABot

  • BOT_CMD_ATTACK = 0
  • BOT_CMD_MOVE = 1
  • BOT_CMD_RETREAT = 2
  • BOT_CMD_RESET = 3

BotQuery

  • BOT_QUERY_NOTARGET = 1

CBaseEntity::TakeDamage, AllowTakeDamage (Bitmasks)

  • DMG_BULLET = 2
  • DMG_BURN = 8
  • DMG_BLAST = 64
  • DMG_MELEE = 2097152 (also known asDMG_SLOWBURNin other Source games)
  • DMG_STUMBLE = 33554432
  • DMG_BLAST_SURFACE = 134217728
  • DMG_BUCKSHOT = 536870912
  • DMG_HEADSHOT = 1073741824

DirectorOptions.OnChangeFinaleStage

  • FINALE_GAUNTLET_1 = 0
  • FINALE_HORDE_ATTACK_1 = 1
  • FINALE_HALFTIME_BOSS = 2
  • FINALE_GAUNTLET_2 = 3
  • FINALE_HORDE_ATTACK_2 = 4
  • FINALE_FINAL_BOSS = 5
  • FINALE_HORDE_ESCAPE = 6
  • FINALE_CUSTOM_PANIC = 7
  • FINALE_CUSTOM_TANK = 8
  • FINALE_CUSTOM_SCRIPTED = 9
  • FINALE_CUSTOM_DELAY = 10
  • FINALE_CUSTOM_CLEAROUT = 11
  • FINALE_GAUNTLET_START = 12
  • FINALE_GAUNTLET_HORDE = 13
  • FINALE_GAUNTLET_HORDE_BONUSTIME = 14
  • FINALE_GAUNTLET_BOSS_INCOMING = 15
  • FINALE_GAUNTLET_BOSS = 16
  • FINALE_GAUNTLET_ESCAPE = 17

Ticker_AddToHud

FLAGS
  • HUD_FLAG_PRESTR = 1
  • HUD_FLAG_POSTSTR = 2
  • HUD_FLAG_BEEP = 4
  • HUD_FLAG_BLINK = 8
  • HUD_FLAG_AS_TIME = 16
  • HUD_FLAG_COUNTDOWN_WARN = 32
  • HUD_FLAG_NOBG = 64
  • HUD_FLAG_ALLOWNEGTIMER = 128
  • HUD_FLAG_ALIGN_LEFT = 256
  • HUD_FLAG_ALIGN_CENTER = 512
  • HUD_FLAG_ALIGN_RIGHT = 768
  • HUD_FLAG_TEAM_SURVIVORS = 1024
  • HUD_FLAG_TEAM_INFECTED = 2048
  • HUD_FLAG_TEAM_MASK = 3072
  • HUD_FLAG_NOTVISIBLE = 16384
SLOTS
  • HUD_LEFT_TOP = 0
  • HUD_LEFT_BOT = 1
  • HUD_MID_TOP = 2
  • HUD_MID_BOT = 3
  • HUD_RIGHT_TOP = 4
  • HUD_RIGHT_BOT = 5
  • HUD_TICKER = 6
  • HUD_FAR_LEFT = 7
  • HUD_FAR_RIGHT = 8
  • HUD_MID_BOX = 9
  • HUD_SCORE_TITLE = 10
  • HUD_SCORE_1 = 11
  • HUD_SCORE_2 = 12
  • HUD_SCORE_3 = 13
  • HUD_SCORE_4 = 14
SPECIAL
  • HUD_SPECIAL_TIMER0 = 0
  • HUD_SPECIAL_TIMER1 = 1
  • HUD_SPECIAL_TIMER2 = 2
  • HUD_SPECIAL_TIMER3 = 3
  • HUD_SPECIAL_COOLDOWN = 4
  • HUD_SPECIAL_ROUNDTIME = 5
  • HUD_SPECIAL_MAPNAME = 6
  • HUD_SPECIAL_MODENAME = 7

ClientPrint

  • HUD_PRINTNOTIFY = 1
  • HUD_PRINTCONSOLE = 2
  • HUD_PRINTTALK = 3
  • HUD_PRINTCENTER = 4

DirectorOptions.InfectedFlags or ReapplyInfectedFlags

  • INFECTED_FLAG_CANT_SEE_SURVIVORS = 8192
  • INFECTED_FLAG_CANT_HEAR_SURVIVORS = 16384
  • INFECTED_FLAG_CANT_FEEL_SURVIVORS = 32768

CTerrorPlayer::GetButtonMask (Bitmasks)

  • IN_ATTACK = 1
  • IN_JUMP = 2
  • IN_DUCK = 4
  • IN_FORWARD = 8
  • IN_BACK = 16
  • IN_USE = 32
  • IN_CANCEL = 64
  • IN_LEFT = 512
  • IN_RELOAD = 8192
  • IN_RIGHT = 1024
  • IN_ATTACK2 = 2048

TerrorNavArea, CNavLadder

  • LADDER_UP = 0
  • LADDER_DOWN = 1

TerrorNavArea, CNavLadder

  • NAV_NORTH = 0
  • NAV_EAST = 1
  • NAV_SOUTH = 2
  • NAV_WEST = 3

DirectorOptions.SpawnSetRule

Note.png Note: This function has a second enum set, but with different name prefixes.
  • SCRIPTED_SPAWN_FINALE = 0
  • SCRIPTED_SPAWN_SURVIVORS = 1
  • SCRIPTED_SPAWN_BATTLEFIELD = 2
  • SCRIPTED_SPAWN_POSITIONAL = 3

SCRIPT_SHUTDOWN To do: Are these for the VS 2010 debugger?

  • SCRIPT_SHUTDOWN_MANUAL = 0
  • SCRIPT_SHUTDOWN_ROUND_RESTART = 1
  • SCRIPT_SHUTDOWN_TEAM_SWAP = 2
  • SCRIPT_SHUTDOWN_LEVEL_TRANSITION = 3
  • SCRIPT_SHUTDOWN_EXIT_GAME = 4

DirectorScript.SpawnDirectionMask (Bitmasks)

  • SPAWNDIR_N = 1
  • SPAWNDIR_NE = 2
  • SPAWNDIR_E = 4
  • SPAWNDIR_SE = 8
  • SPAWNDIR_S = 16
  • SPAWNDIR_SW = 32
  • SPAWNDIR_W = 64
  • SPAWNDIR_NW = 128

DirectorOptions.PreferredMobDirection, DirectorOptions.PreferredSpecialDirection

  • SPAWN_NO_PREFERENCE = -1
  • SPAWN_ANYWHERE = 0
  • SPAWN_BEHIND_SURVIVORS = 1
  • SPAWN_NEAR_IT_VICTIM = 2
  • SPAWN_SPECIALS_IN_FRONT_OF_SURVIVORS = 3
  • SPAWN_SPECIALS_ANYWHERE = 4
  • SPAWN_FAR_AWAY_FROM_SURVIVORS = 5
  • SPAWN_ABOVE_SURVIVORS = 6
  • SPAWN_IN_FRONT_OF_SURVIVORS = 7
  • SPAWN_VERSUS_FINALE_DISTANCE = 8
  • SPAWN_LARGE_VOLUME = 9
  • SPAWN_NEAR_POSITION = 10

DirectorOptions.SpawnSetRule

Note.png Note: This function has a second enum set, but with different name prefixes.
  • SPAWN_FINALE = 0
  • SPAWN_SURVIVORS = 1
  • SPAWN_BATTLEFIELD = 2
  • SPAWN_POSITIONAL = 3

DirectorOptions.ScriptedStageType

  • STAGE_PANIC = 0
  • STAGE_TANK = 1
  • STAGE_DELAY = 2
  • STAGE_CLEAROUT = 4
  • STAGE_SETUP = 5
  • STAGE_ESCAPE = 7
  • STAGE_RESULTS = 8
  • STAGE_NONE = 9

TraceLine (Bitmasks)

  • TRACE_MASK_ALL = -1
  • TRACE_MASK_VISION = 33579073
  • TRACE_MASK_VISIBLE_AND_NPCS = 33579137
  • TRACE_MASK_PLAYER_SOLID = 33636363
  • TRACE_MASK_NPC_SOLID = 33701899
  • TRACE_MASK_SHOT = 1174421507

HUDManageTimers

  • TIMER_DISABLE = 0
  • TIMER_COUNTUP = 1
  • TIMER_COUNTDOWN = 2
  • TIMER_STOP = 3
  • TIMER_SET = 4

CTerrorPlayer::GiveUpgrade

  • UPGRADE_INCENDIARY_AMMO = 0
  • UPGRADE_EXPLOSIVE_AMMO = 1
  • UPGRADE_LASER_SIGHT = 2

ZSpawn

  • ZOMBIE_NORMAL = 0
  • ZOMBIE_SMOKER = 1
  • ZOMBIE_BOOMER = 2
  • ZOMBIE_HUNTER = 3
  • ZOMBIE_SPITTER = 4
  • ZOMBIE_JOCKEY = 5
  • ZOMBIE_CHARGER = 6
  • ZOMBIE_WITCH = 7
  • ZOMBIE_TANK = 8
  • ZSPAWN_MOB = 10
  • ZSPAWN_MUDMEN = 12
  • ZSPAWN_WITCHBRIDE = 11

See also