L4D2 Director Scripts

From Valve Developer Community
Revision as of 20:10, 14 April 2014 by Rectus (talk | contribs) (Created page with "{{toc-right}}{{sq}}{{l4d2}} '''Left 4 Dead 2 Director scripts''' are vscripts that are primarily used to influence the behavior of the AI Director. They are ext...")

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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 are executed with inputs to the info_director entity. A DirectorOptions table is used to give new temporary values for the variables the director uses for decision making. Additional commands can be accessed through the Director object. Only one Director script can be running at a time.

Inputs

BeginScript <script name>
Executes a generic Director script, for example for onslaught events or changing spawning behavior.
EndScript
Ends the running script and resets the Director options to the map specific values.
BeginScriptedPanicEvent <script name>
Begins a Scripted Panic event.

Onslaughts

To do


Finales and Scripted Panic events

Finales and scripted Panic events consist of a number of different kind of stages set in DirectorOptions.

The Director script for the finale is always loaded from <map name>_finale.nut. Scripted panic events are launched from the info_director ScriptedPanicEvent input.


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

  • PANIC - A panic event, the value is the number of waves of infected.
  • TANK - Spawn a tank(s), the value is the number of tanks to spawn.
  • DELAY - A delay, the value is the number of seconds to wait before proceeding to the next stage.
  • SCRIPTED (also called ONSLAUGHT) - The value should be the name of a VScript to call or "" (which will do nothing), any bad value here will crash you to the desktop. Your script is responsible for sending an EndCustomScriptedStage input to the director (a goal of your choice, like a certain trigger volume, timer, random value, etc.). trigger_finale input AdvanceFinaleState may also work. Otherwise, the onslaught will not end.


An example custom finale script:

ERROR <- -1
PANIC <- 0
TANK <- 1
DELAY <- 2
SCRIPTED <- 3 

DirectorOptions <-
{
	//-----------------------------------------------------
	 A_CustomFinale_StageCount = 8 // Number of stages. Used for calculating the Versus score.
	 
	 A_CustomFinale1 = PANIC
	 A_CustomFinaleValue1 = 2   // Two panic waves.
	 
	 A_CustomFinale2 = DELAY
	 	A_CustomFinaleValue2 = 12  // Delay for twelve seconds in addition to stage delay.
	 
	 A_CustomFinale3 = TANK
	 A_CustomFinaleValue3 = 3  // 3 tanks!
	 
	 A_CustomFinale4 = DELAY
	 A_CustomFinaleValue4 = 12 // Wait some more.
	 
	 A_CustomFinale5 = SCRIPTED
	 A_CustomFinaleValue5 = "my_scripted_stage.nut" // Run a custom scripted stage using a separate script.
	 
	 A_CustomFinale6 = DELAY
	 A_CustomFinaleValue6 = 15 // Wait 15 seconds.
	 
	 A_CustomFinale7 = TANK
	 A_CustomFinaleValue7 = 1  // One more tank.

	 A_CustomFinale8 = DELAY
	 A_CustomFinaleValue8 = 10 // Wait ten seconds ... rescue!


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

	 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 );
      MapScript.DirectorOptions.CommonLimit <- num * 10 // Increase commons by 10 linearly with stages.
}


DirectorOptions

The DirectorOptions table is used for changing various variables that govern among other things, infected spawning, finale stages and more.


Information about some of the Director Options found in the Steam Forums.

Warning: NEVER use the = operator when trying to influence the director. Use <-. The difference is semantics. If you use =, it will throw an error if the table slot isn't defined (like if a previous script didn't define it). <-, on the other hand, will create the variable if it does not exist. Some of these samples are only portions of a full script, so make sure that the variables are created beforehand.

To do: Make these into a table.

General

Name Type Default value Description
AllowCrescendoEvents bool
AllowWitchesInCheckpoints bool
AlwaysAllowWanderers bool
BehindSurvivorsSpawnDistance Appears to require PreferredSpecialDirection = SPAWN_BEHIND_SURVIVORS


  • BileMobSize = number of commons that spawn when a bile bomb is thrown. Appears to only work in finale. Found in Dead Center and The Sacrifice finales.
  • BoomerLimit = maximum number of boomers allowed
  • BuildUpMinInterval
  • ChargerLimit = maximum number of chargers allowed
  • ClearedWandererRespawnChance = percent chance (0-100) that cleared nav areas will get re-populated with wanderers.
  • CommonLimit = maximum number of commons allowed
  • DisallowThreatType = ZOMBIE_WITCH, ZOMBIE_TANK (other values???) Ex: c8m1_apartment.nut
  • FallenSurvivorPotentialQuantity = int
  • FallenSurvivorSpawnChance = float [0...1]
  • DominatorLimit To do: confirm category/working
  • GasCansOnBacks = true|false
  • HunterLimit = maximum number of hunters allowed
  • IgnoreNavThreatAreas = ??? (not sure what this does)
  • InfectedFlags = INFECTED_FLAG_CANT_SEE_SURVIVORS, INFECTED_FLAG_CANT_HEAR_SURVIVORS, INFECTED_FLAG_CANT_FEEL_SURVIVORS
  • IntensityRelaxAllowWanderersThreshold
  • IntensityRelaxThreshold = All survivors must be below this intensity before a Peak is allowed to switch to Relax (in addition to the normal peak timer)
  • IntensityThreshold
  • JockeyLimit = maximum number of jockeys allowed
  • LockTempo = (0/1) Endless panics consist of: spawn horde -> BUILD_UP -> SUSTAIN_PEAK -> RELAX -> spawn horde again. Locktempo = 1 removes the "BUILD_UP -> SUSTAIN_PEAK -> RELAX" bit making your hordes spawn constantly without a delay.
  • MaxSpecials = number of specials allowed at once
  • MegaMobMaxSize = maximum megamob size
  • MegaMobMinSize = minimum megamob size
  • MegaMobSize To do: confirm category/working
  • MinimumStageTime = in seconds Ex: c1m4_delay.nut To do: possibly finale or custom panic event specific
  • MobMaxPending = Guessing it's the maximum mob size that can be pending for spawn.
  • MobMaxSize = max mob size
  • MobMinSize = min mob size
  • MobRechargeRate = Guessing it's the speed at which a mob regenerates (ie next mob)
  • MobSpawnMaxTime = max time in seconds for mob spawn
  • MobSpawnMinTime = min time in seconds? for mob spawn
  • MobSpawnSize
  • MusicDynamicMobScanStopSize = When see fewer than this many of a mob, music stops
  • MusicDynamicMobSpawnSize = ???Spawning a mob this large can play music
  • MusicDynamicMobStopSize = When a mob gets to this size we think about stopping the music
  • NumReservedWanderers = the number of infected that cannot be absorbed
  • PanicForever * this seems to only work in gauntlets
  • PanicWavePauseMax (float) To do: confirm category/working
  • PanicWavePauseMin (float) To do: confirm category/working
  • PreferredMobDirection = 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: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. SPAWN_LARGE_VOLUME is what makes you be a mile away on DC finale.
  • PreferredSpecialDirection
Note:The same values for PreferredMobDirection appear to work, BUT I've also seen the following, I don't know if it's just redundancy or what.

SPAWN_SPECIALS_ANYWHERE

SPAWN_SPECIALS_IN_FRONT_OF_SURVIVORS
  • PreTankMobMax = int To do: confirm category/working; possibly gauntlet specific
  • ProhibitBosses = true|false - prohibit tanks/witches
  • RelaxMaxFlowTravel = 600
  • RelaxMaxInterval = 5
  • RelaxMinInterval = 5
  • ShouldAllowMobsWithTank = true|false
  • ShouldAllowSpecialsWithTank = true|false
  • ShouldConstrainLargeVolumeSpawn = true|false
  • SmokerLimit = maximum number of smokers allowed
  • SpawnDirectionMask = a bitfield (using SPAWNDIR_N, _NE, _E, etc) of directors to spawn from _relative to_ a map entity named "Compass" in your map. So the idea is that if you are making a mutation in a confined area, put the compass at the middle (angle determines north) and then you can spawn relative directions around it. Note this layers onto the SpawnSetRule - i.e. if you set a POSITIONAL rule south of the compass, and then set a SpawnDirectonMask of SPAWNDIR_N, the Director will never find a valid place to spawn (since the position is saying "pick from this radius south of here" and the mask is saying "now take that list of valid places and find one north")
  • SpawnSetRule = SPAWN_FINALE, SPAWN_BATTLEFIELD, SPAWN_SURVIVORS, SPAWN_POSITIONAL
    • SpawnSetRadius/SpawnSetPosition: A radius in units, a Vector(x,y,z) center point for POSITIONAL spawning
  • SpecialInfectedAssault = ??? (not sure what this does)
  • SpecialInitialSpawnDelayMin
  • SpecialInitialSpawnDelayMax
  • SpecialRespawnInterval = time in seconds for special respawns
  • SpitterLimit = maximum number of spitters allowed
  • SurvivorMaxIncapacitatedCount = Maximum amount of survivor incapacitating before dying
  • SustainPeakMaxTime = in minutes
  • SustainPeakMinTime = in minutes
  • TankHitDamageModifierCoop = float (mutation1.nut Last Man on Earth) {todo|confirm category}}
  • TankHitDamageModifierVersus = float To do: confirm category
  • TankLimit = maximum number of tanks allowed (for example, used in c7m3_port.nut)
  • TankRunSpawnDelay = in seconds (mutation19.nut Taaannnkk!) To do: confirm category
  • TempHealthDecayRate = 0.27 // pain_pills_decay_rate default, higher values equals quicker decay
  • TotalBoomers = number of boomers allowed in a wave
  • TotalChargers = number of chargers allowed in a wave
  • TotalHunters = number of hunters allowed in a wave
  • TotalJockeys = number of jockeys allowed in a wave
  • TotalSmokers = number of smokers allowed in a wave
  • TotalSpecials = number of specials allowed in a wave
  • TotalSpitters = number of spitters allowed in a wave
  • WanderingZombieDensityModifier = float To do: confirm category/working
  • WitchLimit = maximum number of witches allowed (used in c7m3_port.nut)
  • ZombieSpawnRange = How far away can zombies spawn?
  • ZombieSpawnInFog = true|false
  • ZombieTankHealth = tanks health
  • function Update()
If you define an Update() function in your vscript, it will run repeatedly much like a Think() function, but ONLY a finale via trigger_finale is triggered, if you have multiple scripts that are running that define it, they all will be called. The use of Update() is also found in the Bleed Out mutation (mutation3.nut), but needs further testing to see see if it behaves the same way like during a finale.

Finale Specific/Related

A normal finale consists of X number of stages. Some variables in DirectorOptions can only be used during finales.

  • A_CustomFinale_StageCount = number of stages. Needs to be set for Versus scoring to function properly.
  • A_CustomFinaleX = stage type (enumerated PANIC, ONSLAUGHT (AKA SCRIPTED), DELAY, TANK), where X is the stage number. Also used in scripted panic events.
  • A_CustomFinaleValueX = Value depends on the stage type above. Also used in scripted panic events. Please see the example.
  • A_CustomFinaleMusicX = Soundscript entry to play. For instance, A_CustomFinaleMusic1 = "C2M5.BadManTank2". Note that c2m5_concert_finale.nut does not use this method and instead opted to use entities within the map instead. In the c2m5 script A_CustomFinaleMusic4 = "", suggesting that no song is actually played automatically via script.
Note:There is also a D_CustomFinale_StageCount, D_CustomFinaleX, etc. found in c3m4_plantation_finale.nut but the difference between A and D are unknown. B_, C_, and E_ are also available. These are likely used to allow multiple staged panic events and/or a finale in the same script.
  • EnforceFinaleNavSpawnRules = ??? Likely used to enforce the finale spawning behavior without running a finale. To do: confirm category/working
  • EscapeSpawnTanks = true|false
  • HordeEscapeCommonLimit = number of commons allowed when the escape vehicle has arrived
  • function OnBeginCustomFinaleStage( num, 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.).
  • function OnChangeFinaleMusic() To do: confirm category/working


Gauntlet Specific/Related

Most of these can be found in director_gauntlet.nut

  • CustomTankKiteDistance (3000 is the default) To do: confirm category/working

Movement Bonus related options. The Movement Bonus successively increases the delay between hordes when the survivors are not making progress toward the Gauntlet goal. The Current Bonus value ticks down every second, allows a horde to spawn when it reaches 0. When a horde spawns the Current Bonus is reset to the Movement Bonus value. The Movement Bonus increases at set intervals, and is reset when the survivors cross the Movement Threshold, which is then incremented. Use director_debug 1 to see the values.

  • GauntletMovementThreshold = float The amount of flow units the survivors can advance before the Movement Bonus is reset.
  • GauntletMovementTimerLength = float The interval between each Movement Bonus increase, in seconds.
  • GauntletMovementBonus = float The initial value, and the amount the movement Bonus increases each interval, in seconds.
  • GauntletMovementBonusMax = float The maximum value that the Movement Bonus can reach.

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, incase any map scripts are changing the global values.

  • ActiveChallenge
  • cm_AggressiveSpecials
  • cm_AllowPillConversion
  • cm_AllowSurvivorRescue
  • cm_AutoReviveFromSpecialIncap Used by "The Last Man On Earth" and "Lone Gunman" mutations (mutation1.nut and mutation17.nut)
  • cm_AutoSpawnInfectedGhosts
  • cm_BaseCommonAttackDamage
  • cm_BaseSpecialLimit
  • cm_CommonLimit
  • cm_DominatorLimit
  • cm_FirstManOut Used by the "Room For One" mutation (mutation10.nut)
  • cm_frustrationTimer
  • cm_HeadshotOnly
  • cm_HealingGnome
  • cm_InfiniteFuel (mutation7.nut Chainsaw Massacre)
  • cm_MaxSpecials
  • cm_NoRescueClosets
  • cm_NoSurvivorBots
  • cm_ProhibitBosses
  • cm_CommonLimit
  • cm_ShouldEscortHumanPlayers
  • cm_ShouldHurry
  • cm_SingleScavengeCluster Used for scavenge cans to spawn one-by-one
  • cm_SpecialRespawnInterval
  • cm_SpecialSlotCountdownTime
  • cm_SpecialsRetreatToCover
  • cm_TankLimit
  • cm_TankRun Used in Taaank! mutation (mutation19.nut)
  • cm_TempHealthOnly Only temporary health
  • cm_VIPTarget
  • cm_WanderingZombieDensityModifier
  • cm_WitchLimit
  • function AllowWeaponSpawn()
Returns true or false if the given classname is allowed to spawn, used by several mutations
  • function ConvertWeaponSpawn()
Converts a weapon spawn of given classname to another, used by several mutations
  • function ConvertZombieClass()
Converts one spawn into another, used by the tankss! mutation (mutation19.nut)
  • function GetDefaultItem()
ID starts from 0 and ends in an unknown point. Return a string of a weapon name to make it a default item for survivors. Used in several mutations
  • function ShouldAvoidItem()
Probably a bot related function or spawn related, not sure

Scavenge Specific/Related

  • ScavengeClusterBonusTime = float To do: confirm category/working
  • ScavengeRoundInitialTime = float To do: confirm category/working
  • ScavengeScoreBonusTime = float (used in mutation13.nut Follow the Liter)

Survival Specific/Related

  • SurvivalSetupTime = (Used in mutation15.nut for Survival Versus with setup time of 90 seconds)

Enumerations

  • Director Enumerations
    Note:These are (or some are) script specific, hence the duplicate values.
    • ALLOW_BASH_ALL = 0
    • ALLOW_BASH_NONE = 2
    • ALLOW_BASH_PUSHONLY = 1
    • BOT_CANT_FEEL = 4
    • BOT_CANT_HEAR = 2
    • BOT_CANT_SEE = 1
    • BOT_CMD_ATTACK = 0
    • BOT_CMD_MOVE = 1
    • BOT_CMD_RESET = 3
    • BOT_CMD_RETREAT = 2
    • BOT_QUERY_NOTARGET = 1
    • DMG_BLAST = 64
    • DMG_BLAST_SURFACE = 134217728
    • DMG_BUCKSHOT = 536870912
    • DMG_BULLET = 2
    • DMG_BURN = 8
    • DMG_HEADSHOT = 1073741824
    • DMG_MELEE = 2097152
    • DMG_STUMBLE = 33554432
    • FINALE_CUSTOM_CLEAROUT = 11
    • FINALE_CUSTOM_DELAY = 10
    • FINALE_CUSTOM_PANIC = 7
    • FINALE_CUSTOM_SCRIPTED = 9
    • FINALE_CUSTOM_TANK = 8
    • FINALE_FINAL_BOSS = 5
    • FINALE_GAUNTLET_1 = 0
    • FINALE_GAUNTLET_2 = 3
    • FINALE_GAUNTLET_BOSS = 16
    • FINALE_GAUNTLET_BOSS_INCOMING = 15
    • FINALE_GAUNTLET_ESCAPE = 17
    • FINALE_GAUNTLET_HORDE = 13
    • FINALE_GAUNTLET_HORDE_BONUSTIME = 14
    • FINALE_GAUNTLET_START = 12
    • FINALE_HALFTIME_BOSS = 2
    • FINALE_HORDE_ATTACK_1 = 1
    • FINALE_HORDE_ATTACK_2 = 4
    • FINALE_HORDE_ESCAPE = 6
    • HUD_FAR_LEFT = 7
    • HUD_FAR_RIGHT = 8
    • HUD_FLAG_ALIGN_CENTER = 512
    • HUD_FLAG_ALIGN_LEFT = 256
    • HUD_FLAG_ALIGN_RIGHT = 768
    • HUD_FLAG_ALLOWNEGTIMER = 128
    • HUD_FLAG_AS_TIME = 16
    • HUD_FLAG_BEEP = 4
    • HUD_FLAG_BLINK = 8
    • HUD_FLAG_COUNTDOWN_WARN = 32
    • HUD_FLAG_NOBG = 64
    • HUD_FLAG_NOTVISIBLE = 16384
    • HUD_FLAG_POSTSTR = 2
    • HUD_FLAG_PRESTR = 1
    • HUD_FLAG_TEAM_INFECTED = 2048
    • HUD_FLAG_TEAM_MASK = 3072
    • HUD_FLAG_TEAM_SURVIVORS = 1024
    • HUD_LEFT_BOT = 1
    • HUD_LEFT_TOP = 0
    • HUD_MID_BOT = 3
    • HUD_MID_BOX = 9
    • HUD_MID_TOP = 2
    • HUD_RIGHT_BOT = 5
    • HUD_RIGHT_TOP = 4
    • HUD_SCORE_1 = 11
    • HUD_SCORE_2 = 12
    • HUD_SCORE_3 = 13
    • HUD_SCORE_4 = 14
    • HUD_SCORE_TITLE = 10
    • HUD_SPECIAL_COOLDOWN = 4
    • HUD_SPECIAL_MAPNAME = 6
    • HUD_SPECIAL_MODENAME = 7
    • HUD_SPECIAL_ROUNDTIME = 5
    • HUD_SPECIAL_TIMER0 = 0
    • HUD_SPECIAL_TIMER1 = 1
    • HUD_SPECIAL_TIMER2 = 2
    • HUD_SPECIAL_TIMER3 = 3
    • HUD_TICKER = 6
    • INFECTED_FLAG_CANT_FEEL_SURVIVORS = 32768
    • INFECTED_FLAG_CANT_HEAR_SURVIVORS = 16384
    • INFECTED_FLAG_CANT_SEE_SURVIVORS = 8192
    • IN_ATTACK = 1
    • IN_ATTACK2 = 2048
    • IN_BACK = 16
    • IN_CANCEL = 64
    • IN_DUCK = 4
    • IN_FORWARD = 8
    • IN_JUMP = 2
    • IN_LEFT = 512
    • IN_RELOAD = 8192
    • IN_RIGHT = 1024
    • IN_USE = 32
    • SCRIPTED_SPAWN_BATTLEFIELD = 2
    • SCRIPTED_SPAWN_FINALE = 0
    • SCRIPTED_SPAWN_POSITIONAL = 3
    • SCRIPTED_SPAWN_SURVIVORS = 1
    • SCRIPT_SHUTDOWN_EXIT_GAME = 4
    • SCRIPT_SHUTDOWN_LEVEL_TRANSITION = 3
    • SCRIPT_SHUTDOWN_MANUAL = 0
    • SCRIPT_SHUTDOWN_ROUND_RESTART = 1
    • SCRIPT_SHUTDOWN_TEAM_SWAP = 2
    • SPAWNDIR_E = 4
    • SPAWNDIR_N = 1
    • SPAWNDIR_NE = 2
    • SPAWNDIR_NW = 128
    • SPAWNDIR_S = 16
    • SPAWNDIR_SE = 8
    • SPAWNDIR_SW = 32
    • SPAWNDIR_W = 64
    • SPAWN_ABOVE_SURVIVORS = 6
    • SPAWN_ANYWHERE = 0
    • SPAWN_BATTLEFIELD = 2
    • SPAWN_BEHIND_SURVIVORS = 1
    • SPAWN_FAR_AWAY_FROM_SURVIVORS = 5
    • SPAWN_FINALE = 0
    • SPAWN_IN_FRONT_OF_SURVIVORS = 7
    • SPAWN_LARGE_VOLUME = 9
    • SPAWN_NEAR_IT_VICTIM = 2
    • SPAWN_NEAR_POSITION = 10
    • SPAWN_NO_PREFERENCE = -1
    • SPAWN_POSITIONAL = 3
    • SPAWN_SPECIALS_ANYWHERE = 4
    • SPAWN_SPECIALS_IN_FRONT_OF_SURVIVORS = 3
    • SPAWN_SURVIVORS = 1
    • SPAWN_VERSUS_FINALE_DISTANCE = 8
    • STAGE_CLEAROUT = 4
    • STAGE_DELAY = 2
    • STAGE_ESCAPE = 7
    • STAGE_NONE = 9
    • STAGE_PANIC = 0
    • STAGE_RESULTS = 8
    • STAGE_SETUP = 5
    • STAGE_TANK = 1
    • TIMER_COUNTDOWN = 2
    • TIMER_COUNTUP = 1
    • TIMER_DISABLE = 0
    • TIMER_SET = 4
    • TIMER_STOP = 3
    • TRACE_MASK_ALL = -1
    • TRACE_MASK_NPC_SOLID = 33701899
    • TRACE_MASK_PLAYER_SOLID = 33636363
    • TRACE_MASK_SHOT = 1174421507
    • TRACE_MASK_VISIBLE_AND_NPCS = 33579137
    • TRACE_MASK_VISION = 33579073
    • UPGRADE_EXPLOSIVE_AMMO = 1
    • UPGRADE_INCENDIARY_AMMO = 0
    • UPGRADE_LASER_SIGHT = 2
    • ZOMBIE_BOOMER = 2
    • ZOMBIE_CHARGER = 6
    • ZOMBIE_HUNTER = 3
    • ZOMBIE_JOCKEY = 5
    • ZOMBIE_NORMAL = 0
    • ZOMBIE_SMOKER = 1
    • ZOMBIE_SPITTER = 4
    • ZOMBIE_TANK = 8
    • ZOMBIE_WITCH = 7
    • ZSPAWN_MOB = 10
    • ZSPAWN_MUDMEN = 12
    • ZSPAWN_WITCHBRIDE = 11

See also