Denizen/0.7/Interact Scripts/Commands

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 affect 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.

	ENGAGE	DURATION:[#]) (NPCID:[#])
Blocks player interaction from triggering the NPC. This may be useful if a long script required the player to listen or watch a series of events and you didn't want the Player to be able to interact while these commands were being taken out. Use with either a DURATION or DISENGAGE. DURATION will automatically DISENGAGE after the specified amount of seconds. If no NPCID is included, the Denizen triggered is used. Remember: While ENGAGED, no scripts will trigger, so be diligent in using! Example Usages - ENGAGE - ENGAGE DURATION:12 NPCID:3 - ENGAGE NPCID:2

	DISENGAGE	(NPCID:[#])
Allowed an ENGAGED Denizen to be interacted with again, the counterpart to the ENGAGE command. Can also specify the NPCID of a different Denizen

	ZAP	([Step #]) ('SCRIPT:[Name of Script]') (DURATION:[#]) ('RANDOM:[#] (#)')
A very powerful command, indeed. This is how Scripts progress through their steps. It is not done automatically, instead, you get to decide how to progress. ZAP used alone will simply progress the Player to the next step in the Script. Note: Denizen does not check whether the step exists, so you can use that to your advantage in an Overlay Script Assignment. If an Integer is used, that step will be used. Specify a SCRIPT to change the active step for a Player in a specific Script. If not specified, the triggering Script is used. A DURATION can be set to provide an automatic "DEZAP" of sorts, reverting the step back after a specific amount of seconds, unless, in that duration another ZAP command has taken place. This can be used as a 'timeout' of sorts. RANDOM can be used to let chance select the step to progress the Player to. If one Integer is included, steps 1 through the chosen number will be randomly selected. You can also use a range of numbers if two Integers are used. Example Usages - ZAP - ZAP 'RANDOM:3 6' DURATION:60 - ZAP 'SCRIPT:Another Script' 6

	WAIT	[# of Seconds]  (QUEUE:TASK|TRIGGER)
Pauses a Queue for a specified amount of seconds. If no QUEUE is specified, the sending queue is used. For example, if the command is sent from an Interact (Triggered) Script, the queue that will be held is the 'Trigger Queue'. Could be useful in advanced usage situations when using both Task Scripts and Interact Scripts together. Example Usages - WAIT 6 - WAIT 30 QUEUE:TASK

	FLAG	'[Flag Name]' OR '[[Flag Name]:[Flag Value]]' OR [[Flag Name]:++|--]' (DURATION:[#])
Requires one of the above arguments. FLAG store variables, or 'flags', 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 TRUE. When RESET, it is FALSE. FLAG can also set Integer (or number) variables, and easily increment or decrease them with the use of the ++ and -- arguments accordingly. The command can also store a String value, see the example below. Using a DURATION will revert the value of the flag to the previous value, if during the duration the flag has not changed. Example Usages - FLAG 'Sample Boolean Flag' - FLAG Alignment:++ - FLAG Alignment:-- - FLAG 'Active Item:60 Feathers' - FLAG HasHealingFlag DURATION:180

	FINISH	('SCRIPT:[Name of Script]')
Marks a script as 'Finished' to check against with the FINISHED requirement. This is kind of like a built-in flag for scripts, and acts much like a Counter, ie. You can FINISH a script multiple times and it will keep track of the total number, unless RESET. Example Usages - FINISH - FINISH 'SCRIPT:Another Script'

	FAIL	('SCRIPT:[Name of Script]')
Marks a script as 'Failed' to check against with the FAILED requirement. This is identical to the FINISH command, except keeps track of 'fails' instead. Again, this is kind of like a built-in flag for scripts, and acts much like a Counter, ie. You can FAIL a script multiple times and it will keep track of the total number, unless RESET. Note: A script can be both 'finished' and 'failed', the two commands work independently. Example Usages - FAIL - FAIL 'SCRIPT:Magic Feathers'

	RESET	('SCRIPT:[Name of Script]')
Sets either FINISHED or FAILED of the specified script to False. Remember: Script names are case sensitive! Example Usages - FAIL - RESET FINISHED 'SCRIPT:Magic Feathers'

Server

	EXECUTE	[ASPLAYER or ASSERVER or ASNPC] ["command and arguments"]
Runs a Minecraft/Bukkit command. Specifying ASPLAYER, ASSERVER, or ASNPC defines how the command should be executed. ASNPC will run the command as the Denizen interacting, temporarily granting OP privileges, if the Denizen NPC is a Human-type NPC. Running ASSERVER will run as a console command, and running ASPLAYER will simply run the command as the Player. When specifying the command and arguments, it is not necessary to use the '/' that is generally used when running commands in-game. You may also use <PLAYER> and <WORLD> as variables inside the command arguments. Example Usages EXECUTE ASSERVER 'gamemode <PLAYER> 2' EXECUTE ASNPC 'toggledownfall' EXECUTE ASPLAYER 'spawn'

The commands below require Vault and a valid permissions system. Though Vault is not required to use Denizen, the commands below DO require Vault and its dependencies to be installed. Remember: Vault is not an economy or permissions system, merely a hook to help Denizen connect to your favorite systems!

	PERMISS	[permission.node]|['GROUP:group name'] (WORLD)|('WORLD:NAME')
Gives the Player either a permissions node or adds a group, if supported by your permissions system. Note: You should not include both a permissions node and a group. If you specify a WORLD argument, it will apply the permissions node/group only to the current world. You can alternatively specify a world with WORLD:worldName. Example Usages - PERMISS modifyworld.* - PERMISS GROUP:HillsideEnemy - PERMISS citizens.* WORLD:testworld

	REFUSE	[permission.node]|['GROUP:group name'] (WORLD)|('WORLD:NAME')
Removes from the Player either a permissions node or a group, if supported by your permissions system. Note: You should not include both a permissions node and a group. If you specify a WORLD argument, it will remove the permissions node/group only to the current world. You can alternatively specify a world with WORLD:worldName. Generally, however you add your permissions or group with PERMISS, you should do the same when removing with REFUSE. Example Usages - REFUSE modifyworld.* - REFUSE GROUP:HillsideEnemy - REFUSE citizens.* WORLD:testworld

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 either single ' ' or double " " around the text!

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.

	CHAT	["The text to chat."] (NPCID:[#]) (NOPLAYER)
Makes the Denizen talk to the player. This is the standard chat mechanism in Denizen. You can also change the NPC doing the talking by specifying a Denizen's C2 NPCID. If you would rather the Denizen NPC not speak to the Player directly, use the NOPLAYER argument. Example Usages - CHAT NOPLAYER "Here ye, hear ye!" - CHAT "Hello there, children!" - CHAT NPCID:6 'I only supply tools to builders!'

	WHISPER	["The text to whisper."] (NPCID:[#]) (NOPLAYER)
Whispers the text to the player. Really just an alternative to CHAT. By default, bystanders can't hear what the NPC whispers to the interacting Player. As with the CHAT command, NPCID can be specified. Using NOPLAYER is possible too, since it may be of use in some circumstances. But remember: by default, no bystanders can see the actual text the NPC Denizen whispers. This can be changed in the config.yml. Example Usages - WHISPER "The password is.. 42." - WHISPER NPCID:2 "Hey, I didn't want to blurt this out so everyone could hear, but..."

	SHOUT	["The text to chat."] (NPCID:[#]) (NOPLAYER)
Shouts the text to players nearby. The range that a bystander can hear an NPC Denizen shout is larger then that of a standard CHAT, so it also has some technical advantages. NPCID can be specified. Using NOPLAYER will drop reference to the Player when talking. You can still reference <PLAYER>, however, if need be. See the example below for an idea for usage. Example Usages - SHOUT "EEEK! a spider!" - SHOUT NOPLAYER "<PLAYER> is a thief! Get him!"

	EMOTE	['The text to emote.'] (NPCID:[#])
Let's the Denizen NPC show emotion. Similar to the /me command in IRC, for example. Could be useful for describing to the player what an NPC Denizen may need, or how the NPC Denizen is feeling. NPCID can be specified to change the Denizen NPC doing the 'emote'. Example Usages - EMOTE 'is looking a bit nervous.' - EMOTE NPCID:82 'thinks you should ask a few questions.' - EMOTE "could use a stiff drink."

	NARRATE	['The text to narrate.']
Makes a message appear to player without sender information. Example Usages - NARRATE "There is a small mailbox here."

	ANNOUNCE	['The text to announce.']
Sends the text as a sever announcement to all players, regardless of their place in the world. Could be especially useful for any kind of administration script. Example Usages - ANNOUNCE "<PLAYER> has found a secret!"

	HINT	(SHORT)
If called from an Interact Script Step with a Chat Trigger, this will output a list of all possible things the player can say to activate a chat trigger. Modifiers: SHORT The Denizen will only say the list of trigger words, instead of the full sentence. Example Usages - HINT - HINT SHORT

Movement

Denizen NPC commands are meant to help bring your Denizen to life by allowing fine-control of small movements. These are not necessarily meant for making the Denizen NPC do large/long activities, those will instead be done by the Activities, which is just now starting to be implemented into Denizen. The next 'large' update will focus on Activities.

	LOOK	LOOK [[DIRECTION]|BOOKMARK:[BOOKMARK_NAME]|[CLOSE|AWAY]] (NPCID:[#]) (DURATION:[#])
This command controls where the NPC Denizen is looking. It requires either a Direction, Bookmark, or look-close trait state. Valid directions: UP, DOWN, LEFT, RIGHT, NORTH, SOUTH, EAST, WEST, AT, and BACK. Looking AT or BACK takes the Player's position for reference. AT will look at the Player, BACK will look away from the player. Using CLOSE

	WALKTO	[BOOKMARK:LocationBookmark] or [ 'BOOKMARK:DenizenName:LocationBookmark'] or [PLAYER] (SPEED:#)
Makes the denizen walk to the specified location bookmark, or to the interacting player. Interrupts any current movement, and pauses the NPC pathing if active. Modifiers: SPEED: is the movement speed, generally should be between 0.1 and 1.5 Example Usages - WALKTO PLAYER - WALKTO 'BOOKMARK:Gary:GarysHouse'

	WALK	(FORWARD:#) (NORTH:#) (SOUTH:#) (EAST:#) (WEST:#) (UP:#) (DOWN:#) (X:#) (Y:#) (Z:#) (SPEED:#)
Makes the denizen walk some distance from its current position. Interrupts any current movement, and pauses the NPC pathing if active. All provided directions are added into one movement. Decimal and negative values are accepted. Modifiers: SPEED: is the movement speed, generally should be between 0.1 and 1.5 FORWARD: makes the Denizen walk in whatever direction it is currently facing. Combine LOOK CLOSE and a negative value to walk directly away from the player. +X is the same as EAST +Y is the same as UP +Z is the same as NORTH Example Usages - WALK NORTH;4 EAST:2.5 - WALK FORWARD:1

	RETURN	(SPEED:#)
Makes the denizen walk back to the position it was at before a call to WALKTO or WALK. Will resume NPC pathing if set. Modifiers: SPEED: is the movement speed, generally should be between 0.1 and 1.5 Example Usages - WALKTO BOOKMARK:Somewhere - RETURN

	PAUSE	(DURATION:#)
Causes the Denizen to stop any pathing or activities. Useful for keeping it in place during an interaction. Modifiers: DURATION: Automatically RESUME after the specified number of seconds. Example Usages - PAUSE - PAUSE DURATION:30

	RESUME
Cancels a previous PAUSE command. Example Usages - RESUME

World Interaction

These commands do something physical to the world or player.

	SWITCH	[BOOKMARK:BlockBookmark] or [BOOKMARK:DenizenName:BlockBookmark] (DURATION:#)
This command will activate a button, switch or pressure plate at the designated block bookmark. Modifiers: DURATION:# Will switch the device again after the specified number of seconds. Example Usages - SWITCH BOOKMARK:LightSwitch DURATION:30 - SWITCH BOOKMARK:Jimbo:JimbosButton

	SPAWN	[ENTITY_TYPE] (QTY:#) (BOOKMARK:LocationBookmark) ('BOOKMARK:Denizen Name:LocationBookmark') (SPREAD:#) ('EFFECT:[POTION_EFFECT] [LEVEL]') ('OPTION:[OPTIONS]')
Spawns a specified amount of entities. If the location bookmark is missing, they will spawn near the Denizen. Modifiers: SPREAD:[#] Increases the 'spread' of the area that the monster can spawn. 'EFFECT:[POTION_EFFECT] [LEVEL]' Applies a potion effect on the monster when spawning. 'OPTION:OptionName OptionsValue' Applies a flag to the Mob. Note: Only works for mobs that can accept the flag. Valid OptionNames are: POWERED, SADDLED, BABY, 'PROFESSION [PROFESSION_TYPE]', SHEARED, 'COLORED [DYE_COLOR]', ANGRY') CREEPER can have POWERED PIG can have SADDLED PIG, SHEEP, COW, VILLAGER, CHICKEN, OCELOT and WOLF can have BABY VILLAGER can have PROFESSION Valid PROFESSION_TYPEs: FARMER, LIBRARIAN, PRIEST, BLACKSMITH, BUTCHER SHEEP can have SHEARED and COLORED WOLF and PIG_ZOMBIE can have ANGRY Example Usages - SPAWN BOAT - SPAWN QTY:3 COW BOOKMARK:Cage - SPAWN VILLAGER 'BOOKMARK:El Notcho:Gate' - SPAWN QTY:10 PIG_ZOMBIE SPREAD:5 - SPAWN QTY:25 ZOMBIE SPREAD:20 'EFFECT:INCREASE_DAMAGE 2' - SPAWN QTY:2 SHEEP 'OPTION:COLORED RED'

	WEATHER	[SUNNY or STORMY or PRECIPITATING]
Changes the Denizen's world's weather to the designated type. Example Usages - WEATHER SUNNY

	STRIKE	(DENIZEN) (BOOKMARK:LocationBookmark) ('BOOKMARK:Denizen Name:LocationBookmark') (NODAMAGE) (NPCID:#)
Lightning at your fingertips. Modifiers: DENIZEN Strike lightning at the Denizen's location instead of the player. LocationBookmark Strike lightning at the location bookmark instead of the player. NPCID:# Strike lightning at the location of the specified NPC (using the npc id) NODAMAGE Lightning is cosmetic and does no damage. Example Usages - STRIKE - STRIKE BOOKMARK:BigTree - STRIKE DENIZEN NODAMAGE

Player Interaction

	GIVE	[MONEY or ID or ID:Data or MATERIAL:Data or MATERIAL] (QTY:#)
Gives something to the Player. If QTY: is not specified default is 1. Example Usages - GIVE MONEY QTY:10 - GIVE 17:2 QTY:3 - GIVE LEAVES:2

	TAKE	[MONEY or ITEMINHAND or ID or ID:Data or MATERIAL:Data or MATERIAL] (QTY:#)
Takes something from the Player. If QTY: is not specified default is 1. Example Usages - TAKE MONEY QTY:1000 - TAKE 17:2 QTY:1 - TAKE LOG:2 - TAKE ITEMINHAND

	CAST	[SpellName] (DURATION:#) (POWER:#) (NPC:#) (PLAYER:PlayerName)
Gives the specified target a potion effect. Valid potion names are the same as the Alchemist's. Modifiers: DURATION:# The effect duration, in seconds. Default is 60. POWER:# The level of the effect, usually 1-5. Default is 1. NPC:# The NPC to cast the effect on, instead of the interacting player. Specify with the NPC id. PLAYER:PlayerName The Player to cast the effect on, instead of the interacting player. Example Usages - CAST SPELL:confusion DURATION:300 POWER:3 - CAST SPELL:speed