Difference between revisions of "Scripted sequence"

From Valve Developer Community
Jump to: navigation, search
m (Reformatted spawnflags according to Template:Fl change)
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{base point|scripted_sequence}}
+
[[File: scripted_sequence.png | right | 300px]]
== Entity description ==
+
{{base point|scripted_sequence}} It is used to make an [[NPC]] play scripted animations.
Grabs an [[NPC]] and makes them play a specified set of animations. The NPC can be told to move to the scripted sequence position or can be told to play the script wherever they currently are. Multiple scripted sequences of the same name will frame-synchronize in the action animation once all the actors have moved to position. This allows tight interaction between actors (one actor grabbing another, hitting them, etc.) The flow is as follows:
 
  
#Move to position using the specified movement animation. If "Move to Position" is set to "None", skip to step 2.
+
A <code>scripted_sequence</code> typically takes a Target NPC which can be set to either move to the sequence's position or play the sequence's animation at the NPC's current position. When the NPC is ready to begin the sequence, it will play the specified animation(s) in a special scripted state which may or may not be interrupted depending on the <code>scripted_sequence</code>'s settings.
#If forced to wait for another actor to move to position, play the pre-action idle animation, otherwise skip to step 3. If there is no pre-action idle specified, "ACT_IDLE" is used.
 
#Fire the "OnBeginSequence" output.
 
#Play the action animation. If no action animation is specified, skip to step 5.
 
#Play the post-action idle animation. If none is specified, skip to step 6. If the "Loop in Post Idle" spawnflag is set, keep playing the post-action idle until the script is canceled. If no post-action idle animation is specified, "ACT_IDLE" is used.
 
#Fire the "OnEndSequence" output.
 
#If a next script to play is specified, hand the NPC to the next script and repeat this process for that script.
 
  
The "MoveToPosition" input runs steps 1 and 2, then waits while playing the pre-action idle animation until the "BeginSequence" input is received.
+
{{tip|Multiple scripted sequences of the same name will frame-synchronize their animations once all the actors have moved to position. This allows tight interaction between actors (one actor grabbing another, hitting them, etc.)}}
 +
 
 +
__TOC__
 +
{{clr}}
 +
 
 +
== Script flow ==
 +
Whenever a <code>scripted_sequence</code> plays with a valid Target NPC, it uses a special flow to make the NPC play its animations in specific, coordinated ways:
 +
 
 +
# Unless the "Start on Spawn" flag ticked, the <code>scripted_sequence</code> remains inert until it is triggered. It will remain inert until the <code>BeginSequence</code> input is received or it is used by a previous <code>scripted_sequence</code>.
 +
# Upon being triggered, the <code>scripted_sequence</code> will look for the nearest NPC specified in "Target NPC".
 +
# When a NPC is found, it will either move to the <code>scripted_sequence</code>'s position or begin standing still depending on the "Move to Position" setting.
 +
# When the NPC reaches the <code>scripted_sequence</code>, it will play the "Pre-Action Idle Animation" if it is set to wait (see below). It will play the animation until all conditions are satisfied. If the script is not set to wait for anything, it will skip this step.
 +
# The <code>scripted_sequence</code> fires its <code>OnBeginSequence</code> output.
 +
# If the <code>scripted_sequence</code> has an Entry Animation, the NPC will play it. If the script does not have an entry animation, it will skip this step.
 +
# The NPC plays the Action Animation. If no action animation is specified in the script, it will skip this step.
 +
# If the <code>scripted_sequence</code> has a Post-Action Idle Animation, the NPC will play it. If no post-action idle animation is specified in the script, it will skip this step. If the "Loop in Post Idle" spawnflag is set, the NPC will continue to play the post-action idle animation until the script is canceled.
 +
# The <code>scripted_sequence</code> fires its <code>OnEndSequence</code> output.
 +
# If the <code>scripted_sequence</code> has a Next Script, the NPC is handed to the target script and this process is repeated automatically. If not, the NPC returns to regular behavior.
 +
 
 +
There are a few external factors which can modify this flow:
 +
 
 +
* If the sequence was triggered by the "Start on Spawn" flag or the <code>MoveToPosition</code> input, the NPC will play the Pre-Action Idle Animation until the <code>BeginSequence</code> input was received. If <code>BeginSequence</code> was used to begin with, it will proceed as normal.
 +
* If the sequence shares its name with other sequences, it will wait for other NPCs to get into position before starting, playing the Pre-Action Idle Animation until all actors are in position. When the script has no remaining dependencies, it will proceed as normal.
 +
* If the Target NPC was asleep (via "Sleep State" or <code>Sleep</code>) when it was grabbed, it will awaken automatically without firing <code>OnWake</code>.
 +
* If the Pre-Idle Idle Animation is the same as the Action Animation, the pre-action idle animation will freeze on its first frame, waiting for the script to start to play the full animation. {{confirm}}
  
 
== Keyvalues ==
 
== Keyvalues ==
Line 68: Line 85:
  
 
== Flags ==
 
== Flags ==
* 4 : Repeatable
+
{{Fl|4|Repeatable}}
* 8 : Leave Corpse ('''Forces NPC corpse to remain rather than fade out''')
+
{{Fl|8|Leave Corpse|Forces NPC corpse to remain rather than fade out. {{confirm|This only seems to be valid for NPCs which don't ragdoll on death (e.g. GoldSrc-era NPCs)}}}}
* 16 : Start on Spawn - Note: this activates the "MoveTo" action only. Action Animation will occur only after the <code>scripted_sequence</code> has been otherwise triggered.
+
{{Fl|16|Start on Spawn|Makes the script search for a NPC and move to its position upon spawning, playing the Pre-Action Idle Animation until <code>BeginSequence</code> is received.}}
* 32: No Interruptions ('''NPC sequence isn't allowed to be interrupted''')
+
{{Fl|32|No Interruptions|Prevents the NPC from being interrupted by damage, etc.}}
* 64: Override AI ('''NPC will be overridden regardless of current state''')
+
{{Fl|64|Override AI|Overrides the NPC's current state to play the script, regardless of whether they're in combat or otherwise.}}
* 128: Don't Teleport NPC at End ('''Don't fixup end position with a teleport when the SS is finished''')
+
{{Fl|128|Don't Teleport NPC at End|Prevents the script from teleporting the NPC to the last animation's end position when the script is finished.}}
* 256: Loop in Post Idle ('''Loop in the post idle animation after playing the action animation''')
+
{{Fl|256|Loop in Post Idle|Makes the NPC loop the Post-Action Idle Animation after it finishes playing the Action Animation.}}
* 512: Priority Script ('''Stops other scripts from stealing spot in queue''')
+
{{Fl|512|Priority Script|Stops other scripts from stealing this script's spot in a NPC's queue.}}
* 1024 : Search Cyclically ('''Start search from last entity found''')
+
{{Fl|1024|Search Cyclically|Searches for the next entity from the last one found.|nofgd=1}}
* 2048 : No Complaints ('''Skip developer warnings''')
+
{{Fl|2048|No Complaints|Suppresses developer warnings.|nofgd=1}}
* 4096 : Allow NPC Death ('''The NPC using this scripted sequence may die without interrupting the scene (used for scripted deaths)''')
+
{{Fl|4096|Allow NPC Death|The NPC using this scripted sequence may die without interrupting the scene. (used for scripted deaths)}}
  
 
== Inputs ==
 
== Inputs ==
Line 88: Line 105:
  
 
{{IO|MoveToPosition|Summons an NPC to the script location. They will play their scripted idle (or "ACT_IDLE" if none is specified) until "BeginSequence" is triggered.|}}
 
{{IO|MoveToPosition|Summons an NPC to the script location. They will play their scripted idle (or "ACT_IDLE" if none is specified) until "BeginSequence" is triggered.|}}
 
+
{{bug|Don't use it for [[npc_antlion| npc_antlion]]! Seems it's overriding ai behaviour, when npc try to fly from high ground to lower as the result we have instance flying stuck with looped animation. (at least with Source SDK 2006), better use BeginSequence. Also set a delay before executing this, around 0.5 or other, depends on height and how many you spawn, don't move them all at same time from window (they will stuck), set a delay!}}
 
{{IO|CancelSequence|Stops the scripted sequence. If fired after a sequence starts, this input will not take effect until the NPC finishes playing the scripted action animation.}}
 
{{IO|CancelSequence|Stops the scripted sequence. If fired after a sequence starts, this input will not take effect until the NPC finishes playing the scripted action animation.}}
  
Line 98: Line 115:
 
{{IO|OnEndSequence|Fires when the action animation completes.|}}
 
{{IO|OnEndSequence|Fires when the action animation completes.|}}
  
{{IO|OnScriptEvent''(01-08)''|Fires when a 'trigger' anim event occurs while playing the script. Use { event 1003 framenum ''(1-8)'' } in the QC.|}}
+
{{IO|OnScriptEvent01|to=OnScriptEvent08|Fires when a 'trigger' anim event occurs while playing the script. Use { event 1003 framenum ''(1-8)'' } in the QC.|}}
 +
 
 +
{{IO|OnFoundNPC|since=mapbase|Fires when a target NPC is found and begins moving to play the script.|}}
  
 
== Locating animations ==
 
== Locating animations ==
Line 119: Line 138:
 
* [[aiscripted_schedule]] - a similar entity.
 
* [[aiscripted_schedule]] - a similar entity.
 
* [[falling headcrab tutorial]] - A tutorial for how to make a headcrab fall, using this entity.
 
* [[falling headcrab tutorial]] - A tutorial for how to make a headcrab fall, using this entity.
 +
* [[Actbusy]] - An alternative to <code>scripted_sequence</code> which doesn't involve setting a NPC in a scripted state.
  
 
[[Category:Entities]]
 
[[Category:Entities]]

Latest revision as of 01:27, 24 April 2020

Scripted sequence.png
scripted_sequence is a point entity available in all Source games. It is used to make an NPC play scripted animations.

A scripted_sequence typically takes a Target NPC which can be set to either move to the sequence's position or play the sequence's animation at the NPC's current position. When the NPC is ready to begin the sequence, it will play the specified animation(s) in a special scripted state which may or may not be interrupted depending on the scripted_sequence's settings.

Tip:Multiple scripted sequences of the same name will frame-synchronize their animations once all the actors have moved to position. This allows tight interaction between actors (one actor grabbing another, hitting them, etc.)

Script flow

Whenever a scripted_sequence plays with a valid Target NPC, it uses a special flow to make the NPC play its animations in specific, coordinated ways:

  1. Unless the "Start on Spawn" flag ticked, the scripted_sequence remains inert until it is triggered. It will remain inert until the BeginSequence input is received or it is used by a previous scripted_sequence.
  2. Upon being triggered, the scripted_sequence will look for the nearest NPC specified in "Target NPC".
  3. When a NPC is found, it will either move to the scripted_sequence's position or begin standing still depending on the "Move to Position" setting.
  4. When the NPC reaches the scripted_sequence, it will play the "Pre-Action Idle Animation" if it is set to wait (see below). It will play the animation until all conditions are satisfied. If the script is not set to wait for anything, it will skip this step.
  5. The scripted_sequence fires its OnBeginSequence output.
  6. If the scripted_sequence has an Entry Animation, the NPC will play it. If the script does not have an entry animation, it will skip this step.
  7. The NPC plays the Action Animation. If no action animation is specified in the script, it will skip this step.
  8. If the scripted_sequence has a Post-Action Idle Animation, the NPC will play it. If no post-action idle animation is specified in the script, it will skip this step. If the "Loop in Post Idle" spawnflag is set, the NPC will continue to play the post-action idle animation until the script is canceled.
  9. The scripted_sequence fires its OnEndSequence output.
  10. If the scripted_sequence has a Next Script, the NPC is handed to the target script and this process is repeated automatically. If not, the NPC returns to regular behavior.

There are a few external factors which can modify this flow:

  • If the sequence was triggered by the "Start on Spawn" flag or the MoveToPosition input, the NPC will play the Pre-Action Idle Animation until the BeginSequence input was received. If BeginSequence was used to begin with, it will proceed as normal.
  • If the sequence shares its name with other sequences, it will wait for other NPCs to get into position before starting, playing the Pre-Action Idle Animation until all actors are in position. When the script has no remaining dependencies, it will proceed as normal.
  • If the Target NPC was asleep (via "Sleep State" or Sleep) when it was grabbed, it will awaken automatically without firing OnWake.
  • If the Pre-Idle Idle Animation is the same as the Action Animation, the pre-action idle animation will freeze on its first frame, waiting for the script to start to play the full animation. [confirm]

Keyvalues

Targetname:

Name (targetname) <string>
The targetname that other entities refer to this entity by.
Entity Scripts (vscripts) <scriptlist> (in all games since <Left 4 Dead 2>)
Space delimited list of VScript files (without file extension) that are executed after all entities have spawned. The scripts are all executed in the same script scope, later ones overwriting any identical variables and functions.
Script think function (thinkfunction) <string> (in all games since <Left 4 Dead 2>)
Name of a function in this entity's script which will be called automatically every 100 milliseconds (ten times a second) for the duration of the script. It can be used to create timers or to simulate autonomous behavior. The return value (if present) will set the time until the next call.
Note:Try to avoid expensive operations in this function, as it may cause performance problems.


Parentname:

Parent (parentname) <targetname>
Specifies a movement parent. An entity will maintain its initial offset from its parent. An attachment point can be added to the end of the name, separated by a comma.


Angles:

Pitch Yaw Roll (Y Z X) (angles) <angle>
This entity's orientation in the world. Pitch is rotation around the Y axis, yaw is the rotation around the Z axis, roll is the rotation around the X axis.

DXLevelChoice:

Minimum DX Level (mindxlevel) <choices>
The entity will not exist if the engine is running outside the given range of DirectX Versions. Replaced by SystemLevelChoice from <Left 4 Dead> Left 4 Dead onwards.
Warning: If these are used, the object may break when the user switches their DirectX settings.
Maximum DX Level (maxdxlevel) <choices>
Target NPC <targetname>
The name or class name (such as 'npc_zombie') of an NPC to use for this script.
Pre Action Idle Animation <string>
The name of the sequence (such as "idle01") or activity (such as 'ACT_IDLE') to play before the action animation if the NPC must wait for the script to be triggered. Use "Start on Spawn" flag or "MoveToPosition" input to play this idle animation.
Entry Animation <string>
The name of the sequence (such as 'reload02') or activity (such as 'ACT_RELOAD') to play when the sequence starts, before transitioning to play the main action sequence.
Action Animation <string>
The name of the main sequence (such as 'reload02') or activity (such as 'ACT_RELOAD') to play.
Post Action Idle Animation <string>
The name of the sequence (such as 'idle01') or activity (such as 'ACT_IDLE') to play after the action animation.
Custom Move Animation <string>
Used in conjunction with the 'Custom movement' setting for the 'Move to Position' property, specifies the sequence (such as 'crouch_run01') or activity (such as 'ACT_RUN') to use while moving to the scripted position.
Loop Action Animation? <boolean>
Repeat permamently "Action animation"? See "Action Animation."
Synch Post Idles <boolean>
Search Radius <radius>
Radius to search within for an NPC to use. 0 searches everywhere.
Repeat Rate ms <boolean>
How long NPC will repeat "Action Animation". See "Action Animation". Useless with "Loop Action Animation?"
Move to Position <choices>
How the NPC will walk to this scripted_sequence.
Literal Value Description
0 No
1 Walk
2 Run
3 Custom movement
4 Instantaneous
5 No - Turn to Face
Next Script <targetname>
The name of the script to run immediately after this script completes. The NPC will not return to AI between the two scripts.
Ignore Gravity on NPC during Script <boolean>
If this is set to 'Yes', the NPC will not be subject to gravity while playing this script
Disable NPC collisions during Script <boolean>
Useful for when NPCs playing scripts must interpenetrate while riding on trains, elevators, etc. This only disables collisions between the NPCs in the script and must be enabled on BOTH scripted_sequences.
On Player death <boolean>
If set, NPC will cancel script and return to AI.

Flags

  •  [4] : Repeatable
  •  [8] : Leave Corpse
Forces NPC corpse to remain rather than fade out.
Confirm:This only seems to be valid for NPCs which don't ragdoll on death (e.g. GoldSrc-era NPCs)
  •  [16] : Start on Spawn
Makes the script search for a NPC and move to its position upon spawning, playing the Pre-Action Idle Animation until BeginSequence is received.
  •  [32] : No Interruptions
Prevents the NPC from being interrupted by damage, etc.
  •  [64] : Override AI
Overrides the NPC's current state to play the script, regardless of whether they're in combat or otherwise.
  •  [128] : Don't Teleport NPC at End
Prevents the script from teleporting the NPC to the last animation's end position when the script is finished.
  •  [256] : Loop in Post Idle
Makes the NPC loop the Post-Action Idle Animation after it finishes playing the Action Animation.
  •  [512] : Priority Script
Stops other scripts from stealing this script's spot in a NPC's queue.
  •  [1024] : Search Cyclically !FGD
Searches for the next entity from the last one found.
  •  [2048] : No Complaints !FGD
Suppresses developer warnings.
  •  [4096] : Allow NPC Death
The NPC using this scripted sequence may die without interrupting the scene. (used for scripted deaths)

Inputs

Targetname:

Kill
Removes this entity from the world.
KillHierarchy
Removes this entity and its children from the world.
Note:Entities already remove orphaned children upon being removed, but this input removes all children on the same frame, being marginally faster than Kill.
AddOutput <string>
Adds a keyvalue/output to this entity. It can be potentially very dangerous, use with care.
KV Format: <key> <value>
I/O Format: <output name> <targetname>:<inputname>:<parameter>:<delay>:<max times to fire, -1 means infinite>
FireUser1 to FireUser4
Fire the OnUser outputs; see User Inputs and Outputs.
Use  !FGD
Same as a player invoking +use; may not do anything depending on the entity. Can also be invoked by firing an output that does not specify an input.
RunScriptFile <script> (in all games since <Left 4 Dead 2>)
Execute a VScript file from disk, without file extension. The script contents are merged with the script scope of the receiving entity.
RunScriptCode <string> (in all games since <Left 4 Dead 2>)
Execute a string of VScript source code in the scope of the entity receiving the input. String quotation may be needed when fired via console.
Bug: In <Left 4 Dead 2>, the code is executed in the script scope of the entity that fires the output, not the one receiving the input.
Warning: Never try to pass string parameters to a script function with this input. It will corrupt the VMF structure because of the nested quotation marks, which then must be removed manually with a text editor.
CallScriptFunction <string> (in all games since <Left 4 Dead 2>) !FGD
Execute a VScript function in the scope of the receiving entity.
SetLocalOrigin <coordinates> (in all games since <Alien Swarm>) !FGD
Send this entity to a spot in the map. If the entity is parented to something, it will be offset from the parent by this amount.
SetLocalAngles <angles> (in all games since <Alien Swarm>) !FGD
Set this entity's angles.


Parentname:

SetParent <string>
Move with this entity. See Entity Hierarchy (parenting).
SetParentAttachment <string>
Change this entity to attach to a specific attachment point on its parent. The entity will teleport so that the position of its root bone matches that of the attachment. Entities must be parented before being sent this input.
SetParentAttachmentMaintainOffset <string>
As above, but without teleporting. The entity retains its position relative to the attachment at the time of the input being received.
ClearParent
Removes this entity from the the movement hierarchy, leaving it free to move independently.
BeginSequence
Summons an NPC to act out the scripted sequence.
MoveToPosition
Summons an NPC to the script location. They will play their scripted idle (or "ACT_IDLE" if none is specified) until "BeginSequence" is triggered.
Bug: Don't use it for npc_antlion! Seems it's overriding ai behaviour, when npc try to fly from high ground to lower as the result we have instance flying stuck with looped animation. (at least with Source SDK 2006), better use BeginSequence. Also set a delay before executing this, around 0.5 or other, depends on height and how many you spawn, don't move them all at same time from window (they will stuck), set a delay!
CancelSequence
Stops the scripted sequence. If fired after a sequence starts, this input will not take effect until the NPC finishes playing the scripted action animation.

Outputs

Targetname:

OnUser1 to OnUser4
These outputs each fire in response to the firing of the like-numbered FireUser1 to FireUser4 Input; see User Inputs and Outputs.
OnKilled  (only in <Left 4 Dead><Left 4 Dead 2>)
This output fires when the entity is killed and removed from the game.
OnBeginSequence
Fires when the action animation begins playing.
OnEndSequence
Fires when the action animation completes.
OnScriptEvent01 to OnScriptEvent08
Fires when a 'trigger' anim event occurs while playing the script. Use { event 1003 framenum (1-8) } in the QC.
OnFoundNPC  (in all games since <Mapbase>)
Fires when a target NPC is found and begins moving to play the script.

Locating animations

You can use the model tab in the entity window.

Or

You can use the Half-life Model Viewer tool to see all the available sequences(Animations) for the model you're using. You can find the application in the Source SDK.

When you've launched the tool go to File and load the model you want. Then go to the Sequence tab and select an animation from the dropdown menu to get the model you've select to play that animation or sequence.

What it looks like: Hlmw.jpg

See also