View source for Denizen/0.7/Interact Scripts/Commands

== Interact Script Commands ==
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Note: There are plenty more to come, be patient, more are coming! Have ideas for a good command? Let me know!

<code>[] indicates required field, () indicates an optional field, OR indicates alternative usage.</code>
</div>

====Script Flow Commands====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
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 <tt>WAIT</tt>, it is generally recommended to run these as <tt>Instant Commands</tt> to ensure smooth Script feedback to players.

{{Denizen Command Color|mintcream|
ENGAGE
| DURATION:[#]) (NPCID:[#])
| <p>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 <tt>DURATION</tt> or <tt>DISENGAGE</tt>. <tt>DURATION</tt> will automatically <tt>DISENGAGE</tt> after the specified amount of seconds. If no <code>NPCID</code> is included, the Denizen triggered is used. Remember: While <tt>ENGAGED</tt>, no scripts will trigger, so be diligent in using!</p>
'''Example Usages'''
<pre>- ENGAGE
- ENGAGE DURATION:12 NPCID:3
- ENGAGE NPCID:2</pre>
}}
{{Denizen Command Color|mintcream|
DISENGAGE
| &nbsp;&nbsp;(NPCID:[#])
| <p>Allowed an <tt>ENGAGED</tt> Denizen to be interacted with again, the counterpart to the <tt>ENGAGE</tt> command. Can also specify the NPCID of a different Denizen</p>
}}
{{Denizen Command Color|mintcream|
ZAP
|([Step #])&nbsp;('SCRIPT:[Name of Script]')&nbsp;(DURATION:[#])&nbsp;('RANDOM:[#] (#)')
| <p>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.</p>
<p>Specify a <tt>SCRIPT</tt> to change the active step for a Player in a specific Script. If not specified, the triggering Script is used. A <tt>DURATION</tt> 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. <tt>RANDOM</tt> 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.</p>
'''Example Usages'''
<pre>- ZAP
- ZAP 'RANDOM:3 6' DURATION:60
- ZAP 'SCRIPT:Another Script' 6</pre>
}}
{{Denizen Command Color|mintcream|
WAIT
| &nbsp;&nbsp;[# of Seconds]&nbsp;&nbsp;(QUEUE:TASK<nowiki>|</nowiki>TRIGGER)
| <p>Pauses a Queue for a specified amount of seconds. If no <tt>QUEUE</tt> 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.</p>
'''Example Usages'''
<pre>- WAIT 6
- WAIT 30 QUEUE:TASK</pre>
}}
{{Denizen Command Color|mintcream|
FLAG
| <nowiki>&nbsp;&nbsp;'[Flag Name]'&nbsp;OR&nbsp;'[[Flag Name]:[Flag Value]]'&nbsp;OR&nbsp;[[Flag Name]:++|--]'&nbsp;(DURATION:[#])</nowiki>
| <p>Requires one of the above arguments. <tt>FLAG</tt> 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 <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.</p>
'''Example Usages'''
<pre>- FLAG 'Sample Boolean Flag'
- FLAG Alignment:++
- FLAG Alignment:--
- FLAG 'Active Item:60 Feathers'
- FLAG HasHealingFlag DURATION:180</pre>
}}
{{Denizen Command Color|mintcream|
FINISH
|&nbsp;&nbsp;('SCRIPT:[Name of Script]')
| <p>Marks a script as 'Finished' to check against with the <tt>FINISHED</tt> requirement. This is kind of like a built-in flag for scripts, and acts much like a Counter, ie. You can <tt>FINISH</tt> a script multiple times and it will keep track of the total number, unless <tt>RESET</tt>.</p>
'''Example Usages'''
<pre>- FINISH
- FINISH 'SCRIPT:Another Script'</pre>
}}
{{Denizen Command Color|mintcream|
FAIL
|&nbsp;&nbsp;('SCRIPT:[Name of Script]')
| <p>Marks a script as 'Failed' to check against with the <tt>FAILED</tt> requirement. This is identical to the <tt>FINISH</tt> 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 <tt>FAIL</tt> a script multiple times and it will keep track of the total number, unless <tt>RESET</tt>. Note: A script can be both 'finished' and 'failed', the two commands work independently.</p>
'''Example Usages'''
<pre>- FAIL
- FAIL 'SCRIPT:Magic Feathers'</pre>
}}
{{Denizen Command Color|mintcream|
RESET
| &nbsp;&nbsp;('SCRIPT:[Name of Script]')
| <p>Sets either FINISHED or FAILED of the specified script to False. Remember: Script names are case sensitive!</p>
'''Example Usages'''
<pre>- FAIL
- RESET FINISHED 'SCRIPT:Magic Feathers'</pre>
}}
</div>

====Server Commands====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
{{Denizen Command Color|mintcream|
EXECUTE
| <nowiki>[ASPLAYER|ASSERVER|ASNPC]</nowiki> '[command with arguments]'
| <p>Runs a Minecraft/Bukkit command. Specifying <tt>ASPLAYER, ASSERVER, or ASNPC</tt> 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.</p>
'''Example Usages'''
<pre>EXECUTE ASSERVER 'gamemode <PLAYER> 2'
EXECUTE ASNPC 'toggledownfall'
EXECUTE ASPLAYER 'spawn'</pre>
}}
</div>

====Text Commands====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
These commands show some text to the player interacting, and usually to bystanders around. Note that all text commands must be surrounded by quotes single ' or double ". See: [[Which_Quotes|Which Quotes?]] for more information. 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: [[Color_Codes|Denizen Color Codes]]. Formatting for how NPCs and Players talk can be customized in the [[config.yml]].

{{Denizen Command Color|lavender|
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 <tt>NOPLAYER</tt> argument.
'''Example Usages'''
<pre>
- CHAT NOPLAYER "Here ye, hear ye!"
- CHAT "Hello there, children!"
- CHAT NPCID:6 'I only supply tools to builders!'
</pre>
}}
{{Denizen Command Color|lavender|
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 <tt>CHAT</tt> 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'''
<pre>
- WHISPER "The password is.. 42."
- WHISPER NPCID:2 "Hey, I didn't want to blurt this out so everyone could hear, but..."
</pre>
}}
{{Denizen Command Color|lavender|
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 <tt>CHAT</tt>, so it also has some technical advantages. <tt>NPCID</tt> can be specified. Using <tt>NOPLAYER</tt> 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'''
<pre>
- SHOUT "EEEK! a spider!"
- SHOUT NOPLAYER "<PLAYER> is a thief! Get him!"
</pre>
}}
{{Denizen Command Color|lavender|
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. <tt>NPCID</tt> can be specified to change the Denizen NPC doing the  'emote'.
'''Example Usages'''
<pre>
- EMOTE 'is looking a bit nervous.'
- EMOTE NPCID:82 'thinks you should ask a few questions.'
- EMOTE "could use a stiff drink."
</pre>
}}
{{Denizen Command Color|lavender|
NARRATE
|['The text to narrate.']
| Makes a message appear to player without sender information.
'''Example Usages'''
<pre>
- NARRATE "There is a small mailbox here."
</pre>
}}
{{Denizen Command Color|lavender|
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'''
<pre>
- ANNOUNCE "<PLAYER> has found a secret!"
</pre>
}}
</div>

====Denizen NPC Commands====
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 [[Activity Engine]], which is just now starting to be implemented into Denizen. The next 'large' update will focus on Activities.

{{Denizen Command Color|mintcream|
LOOK
| LOOK [[DIRECTION]|BOOKMARK:[BOOKMARK_NAME]|[CLOSE|AWAY]] (NPCID:[#]) (DURATION:[#])
| <p>This command controls where the NPC Denizen is looking. It requires either a Direction, Bookmark, or look-close trait state. Valid directions: <tt>UP, DOWN, LEFT, RIGHT, NORTH, SOUTH, EAST, WEST, AT, and BACK</tt>. Looking <tt>AT</tt> or <tt>BACK</tt> takes the Player's position for reference. AT will look at the Player, <tt>BACK</tt> will look away from the player. Using <tt>CLOSE|AWAY</tt> will toggle the NPC's <tt>look-close trait</tt>. <tt>CLOSE</tt> will make the NPC's head follow the closest Player to it. You can toggle off this behavior by using <tt>AWAY</tt>, not to be confused with <tt>BACK</tt>. If you specify a Location Bookmark instead of a direction, the NPC will take the pitch and yaw from the information stored in the bookmark. Note: This does not affect the actual position of the NPC Denizen, only the head position. Using a <tt>DURATION</tt> argument will restore the previous head position after that amount of time. Note: The script queue will continue as normal, so if the NPC moves or uses another LOOK command in this duration, it may get glitchy. Either time your commands appropriately, or use a <tt>WAIT</tt> command to compensate. The optional argument <tt>NPCID</tt> will change the Denizen NPC doing the looking. 
'''Example Usages'''
<pre>- LOOK UP
- LOOK CLOSE NPCID:32
- LOOK BOOKMARK:HiddenChest DURATION:3</pre>
}}

<del>* FOLLOW [PLAYER|NOBODY]</del>
<del>*: </code>Makes the Denizen follow the player, or stop following the player.<code></del>

* WALKTO [Location Bookmark]
*: </code>Makes the Denizen walk to a specified location.<code>
Note: I've been having problems getting the NPCs to WALKTO a bookmarked location that is far away, perhaps in a different chunk? Working on it with the C2 team. I may have another workaround as well.

* WALK [Z] [X] [Y]   Note: Z(-NORTH(2)/+SOUTH(0)) X(-WEST(1)/+EAST(3)) Y (+UP/-DOWN)
*: </code>Makes the Denizen walk. This is not for making the Denizen to specific coordinates. The values for X Y and Z will get added or subtracted from the Denizen's current location.<code>

* RETURN
*: </code>Can be used after initiating a WALK command.  This will make the denizen return to its previous location.<code>

<del> RESPAWN [Location Bookmark]
*: </code>Despawns the Denizen and respawns it to a bookmarked location.<CODE>
Note: There is something funny going on with NPCs spawning to a location you are very near to. You sometimes have to back away before they show up. This seems to be an issue with Craftbukkit and/or Minecraft Server.</code> </del>

====Vault Commands====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
The commands below require Vault and a valid permissions and economy 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!

{{Denizen Command Color| whitesmoke|
PERMISS
|<nowiki>[permission.node]|['GROUP:group name'] (WORLD)|('WORLD:NAME')</nowiki>
| <p>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 <tt>WORLD</tt> argument, it will apply the permissions node/group only to the current world. You can alternatively specify a world with <tt>WORLD:worldName</tt>.</p>
'''Example Usages'''
<pre>
- PERMISS modifyworld.*
- PERMISS GROUP:HillsideEnemy
- PERMISS citizens.* WORLD:testworld
</pre>
}}
{{Denizen Command Color| whitesmoke|
REFUSE
|<nowiki>[permission.node]|['GROUP:group name'] (WORLD)|('WORLD:NAME')</nowiki>
| 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 <tt>WORLD</tt> argument, it will remove the permissions node/group only to the current world. You can alternatively specify a world with <tt>WORLD:worldName</tt>. Generally, however you add your permissions or group with <tt>PERMISS</tt>, you should do the same when removing with <tt>REFUSE</tt>.
'''Example Usages'''
<pre>
- REFUSE modifyworld.*
- REFUSE GROUP:HillsideEnemy
- REFUSE citizens.* WORLD:testworld
</pre>
}}
</div>

====World Interaction Commands====
These commands do something physical to the world or player.

{{Denizen Command Color|wheat|
SWITCH 
|[BOOKMARK:Location Bookmark] or [BOOKMARK:DenizenName:LocationBookmark]
| This command will activate a button, switch or pressure plate at the designated '''location''' bookmark.
Modifiers:
*DURATION:##
:: Will switch the button/lever back after the specified number of seconds.
'''Example Usages'''
<pre>
- SWITCH BOOKMARK:LightSwitch DURATION:30
- SWITCH BOOKMARK:Jimbo:JimbosButton 
</pre>
}}



* SPAWN [ENTITY_TYPE] [AMOUNT] (Location Bookmark)
*: </code>Spawns a specified amount of entities. If the location bookmark is missing, they will spawn near the Denizen.<CODE>

* TELEPORT [Denizen Name] OR [BOOKMARK:BookmarkName] OR ['BOOKMARK:Denizen Name:BookmarkName']
*: </code>Teleports the player interacting to a bookmark or Denizen/ <code>

{{Denizen Command Color|wheat|
STRIKE
| (DENIZEN) (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'''
<pre>
- STRIKE
- STRIKE DENIZEN NODAMAGE
</pre>
}}

====Player Interaction Commands====
* GIVE [MONEY|#(:#)|MATERIAL_TYPE(:#)] (QTY:#)
*: </code>Denizen will drop specified items.<CODE>

* TAKE [MONEY|ITEMINHAND|#(:#)|MATERIAL_TYPE(:#)] (QTY:#)
*: </code>Takes specific item or money from the player.<CODE>



{{Denizen Command Color|palegreen|
CAST
| [SPELL:SpellName] (DURATION:#) (POWER:#) (NPC:#) (PLAYER:PlayerName)
| Gives the specified target a potion effect.  [[Alchemist#Valid_Effects | Valid potion names are the same as the Alchemist's.]] 
Modifiers:
*DURATION:#
::The effect duration, in seconds.
*POWER:#
::The level of the effect, usually 1-5.
*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'''
<pre>
- CAST SPELL:confusion DURATION:300 POWER:3
- CAST SPELL:speed
</pre>
}}