Denizen/0.7/Interact Scripts/Commands: Difference between revisions

From Citizens Wiki
m (→‎Script Flow: Added missing word.)
(→‎Script Flow: Added IS_NUMBER and ELSE modifiers to IF command.)
Line 104: Line 104:
FLAG
FLAG
|['Flag Name' or 'Flag Name:Flag Value' or 'Flag Name:++' or 'Flag Name:--'] (PLAYER or DENIZEN or GLOBAL) (DURATION:#)
|['Flag Name' or 'Flag Name:Flag Value' or 'Flag Name:++' or 'Flag Name:--'] (PLAYER or DENIZEN or GLOBAL) (DURATION:#)
| <p>Requires one of the above arguments. <tt>FLAG</tt> stores variables, or 'flags', by default to a Player. This can be used to keep track of information that can be check against with the FLAGGED requirement. Usage of the command is easy, and can be used in 3 different ways. A Boolean (true/false) value can be set with only a flag name. If set, the value is <tt>TRUE</tt>. When <tt>RESET</tt>, it is <tt>FALSE</tt>. <tt>FLAG</tt> can also set Integer (or number) variables, and easily increment or decrease them with the use of the <tt>++</tt> and <tt>--</tt> arguments accordingly. The command can also store a String value, see the example below. Using a <tt>DURATION</tt> will revert the value of the flag to the previous value, if during the duration the flag has not changed. Using the PLAYER modifier will set the flag on the Player (which is the default behaviour). Using the DENIZEN modifier will set a flag on the Denizen instead of the Player. Using the GLOBAL modifier will set a flag independent of a Player or Denizen.</p>
| <p>Requires one of the above arguments. <tt>FLAG</tt> stores variables, or 'flags', by default to a Player. This can be used to keep track of information that can be check against with the FLAGGED requirement. Usage of the command is easy, and can be used in 3 different ways. A Boolean (true/false) value can be set with only a flag name. If set, the value is <tt>TRUE</tt>. When <tt>RESET</tt>, it is <tt>FALSE</tt>. <tt>FLAG</tt> can also set Integer (or number) variables, and easily increment or decrease them with the use of the <tt>++</tt> and <tt>--</tt> arguments accordingly. The command can also store a String value, see the example below. Using a <tt>DURATION</tt> will revert the value of the flag to the previous value, if during the duration the flag has not changed. Using the PLAYER modifier will set the flag on the Player (which is the default behavior). Using the DENIZEN modifier will set a flag on the Denizen instead of the Player. Using the GLOBAL modifier will set a flag independent of a Player or Denizen.</p>
'''Example Usages'''
'''Example Usages'''
<pre>- FLAG 'Sample Boolean Flag'
<pre>- FLAG 'Sample Boolean Flag'
Line 117: Line 117:
{{Denizen Command Color 2|mintcream|
{{Denizen Command Color 2|mintcream|
IF
IF
|(EXACTLY) (PLAYER or DENIZEN or GLOBAL) (-)[FLAG:Value] [FLAG]  '[SCRIPT:Task Script to Run]' (QUEUETYPE:TRIGGER) (QUEUETYPE:TASK) (APPEND)
|(EXACTLY) (PLAYER or DENIZEN or GLOBAL) (-)[FLAG:Name or FLAG:Name:Value] (IS_NUMBER) '[SCRIPT:Script Run When Condition Met]' (QUEUETYPE:TRIGGER) (QUEUETYPE:TASK) (APPEND) (ELSE '[SCRIPT:Script Run When Condition Not Met]')
|Checks the value of a FLAG and runs a TASK script if it passes. By default the TASK script will run before the interact script continues.
|Checks the value of a FLAG and runs a TASK script if the condition is met. By default the TASK script will run before the interact script continues.
Modifiers:
Modifiers:
*EXACTLY - For integer flags only passes if the value matches exactly. By default passes if value is greater than or equal.
*EXACTLY - For integer flags, the IF condition is met only if the value matches exactly. By default, the condition is met if the flag's value is greater than or equal to the value it is checked against, i.e. IF 'FLAG:AGE:13' will pass for any AGE that is at least 13, but IF EXACTLY 'FLAG:AGE:13' will only pass if the AGE is 13.
*PLAYER - check a flag set on this Player (which is the default behaviour)
*PLAYER - Check a flag set on this Player (which is the default behavior)
*DENIZEN - check a DENIZEN flag set on the Denizen itself instead of a flag on this Player
*DENIZEN - Check a DENIZEN flag set on the Denizen itself instead of a flag on this Player
*GLOBAL - check a GLOBAL flag instead of a flag on this Player
*GLOBAL - Check a GLOBAL flag instead of a flag on this Player
*IS_NUMBER - The IF condition is met only if the value of the flag is an integer or double.
*APPEND - Runs the TASK after this script completes, instead of before the next command.
*APPEND - Runs the TASK after this script completes, instead of before the next command.
*QUEUETYPE - Specify which queue to run the commands, defaults to the executing queue type.
*QUEUETYPE - Specify which queue to run the commands, defaults to the executing queue type.
*ELSE - Choose a TASK script to run when the IF condition is not met.
'''Example Usages'''
'''Example Usages'''
<pre>
<pre>
- IF FLAG:BossDead SCRIPT:Reward APPEND
- IF FLAG:BossDead SCRIPT:Reward APPEND
- IF EXACTLY FLAG:Stage:4 SCRIPT:Stage4Instructions
- IF EXACTLY FLAG:Stage:4 SCRIPT:Stage4Instructions
- IF 'FLAG:AGE:13' 'SCRIPT:Meets Minimum Age' ELSE 'SCRIPT:Does Not Meet Minimum Age'
</pre>
</pre>
}}
}}

Revision as of 17:22, 30 September 2012

Interact Script Commands are used to make the Denizen perform actions in an Interact Script. They are written in a YAML sequence under the Script node of an Interact Trigger. A single entry in the sequence contains a Command and Modifiers. Some commands have no available modifiers.

Syntax

Syntax is very important for proper execution.

  • Placing a caret ^ in front of the command name causes that command to ignore the normal 0.5 second delay between commands.
  • The command must be upper-case (i.e CHAT not chat)
  • Modifiers are not case sensitive.
  • Modifiers in [Brackets] are required for the command to execute. [A or B] means either A or B is required.
  • Modifiers in (Parentheses) are optional, and generally change the default behavior of the command.
  • Modifiers that take a value are of the form MODIFIER:VALUE.
    • If the VALUE of the modifier contains a space, such as in the case of a NPC or script name, the whole modifier must be put in quotes.
Example: - TELEPORT BOOKMARK:Bob:Bobshouse is okay, but - TELEPORT 'BOOKMARK:Bob Jones:Bobshouse' requires the quotes to function properly.

Example:

Some Trigger:
  Script:
  - COMMAND1 MODIFIER1 MODIFIER2:VALUE
  - COMMAND2 'MODIFIER1:Value With Spaces'
  - ^COMMAND3 'This will run instantly after COMMAND2'

List of Commands

Script Flow

These commands have no external effect on the world, but can control the flow of scripts within Denizen. Though not required, and with the exception of WAIT, it is generally recommended to run these as Instant Commands to ensure smooth Script feedback to players.

Server

The commands below require [Vault] and a valid permissions system.

Speech

These commands show some text to the player interacting, and usually to bystanders around. Text commands also have some auto-formatting, such as making sure no words will be cut off on long messages, and applying color codes. See: Denizen Color Codes. Formatting for how NPCs and Players talk can be customized in the Denizen/config.yml.

  • All Speech commands require quotes (single (' ') or double (" ")) around the text. If your text has an apostrophe (') in it, you MUST use double quotes (" ")!!

You can use the following placeholders to fill in specific information:

  • <NPC> - The Denizens's name.
  • <PLAYER> - The interacting Player's name
  • <DISPLAYNAME> - The interacting Player's display name
  • <HEALTH> - The interacting Player's heath
  • <WORLD> - The name of the Denizen's world

If you use the NOPLAYER modifier on a text command the <PLAYER>, <DISPLAYNAME> and <HEALTH> tags are not available.

Denizen Interaction

Denizen interaction commands are meant to help bring your Denizen to life by allowing fine control of movement and actions during scripts. These are not meant for making the Denizen do continuous movement and actions, that should instead be done via Activities.

World Interaction

Player Interaction

These commands default to affecting the interacting player. Most have modifiers to affect the executing Denizen instead.