Script Commands

Script Commands are what tell the script interpreter what main action you want to preform. Each line of a script must start with one and only one of these commands per line. Most script commands take one or more arguments denoted with [ ]. You may use $Object.Variables, <placeholders> and <functionalplaceholders:> as any argument or part of an argument in the script command. Ampersand Color codes &a-&f, &1-&9 and Special codes &l &n &o &m &r are incorporated in this plugin, so use them in any text that will be displayed.

When typing In-Game Commands that let you add a script line to a trigger, a few of the arguments are optional, meaning you may type it in or it will ask you to click a location and it will be entered for you. [Location] arguments for instance are one of these. You may enter the x,y,z manualy or leave it blank and you will be prompted to click the location. [BlockID:Data] is another optional one. If you leave it blank it will be filled in for you when you click the block.


//	Comments. Any line starting with `//` are comments and will be ignored.

Feedback

Messaging and chat commands.

@QUIET	Prevents all chat from being displayed on selected player for the number of seconds.
	Usage: @QUIET [PLAYERNAME] [SECONDS]
	This can be handy for when you want to display a message to a player and you don't want all the chating to scroll the text off screen. Seconds may be decimal 5.5 or 3.6 or just 5

@CLEARCHAT	Wipes the chat window clean for someone.
	Usage: @CLEARCHAT [player]

@BROADCAST	Broadcast a message to the whole server. Color codes &a-&f, &1-&9 and Special codes &l &n &o &m &r are welcome.
	Usage: @BROADCAST [TEXT MESSAGE]

@PLAYER	Displays text only to the triggering Player. You may use the minecraft color codes &1-&f and special codes &l, &m, &0, &k, &m in any text that will be displayed to the players.
	Usage: @PLAYER [TEXT MESSAGE]

@TELL	Displays text only to the specified Player. You may use the minecraft color codes &1-&f and special codes &l, &m, &0, &k, &m in any text that will be displayed to the players.
	Usage: @TELL [PLAYERNAME] [TEXT MESSAGE]

@PRINT	Prints something to console (for debugging?)
	Usage: @PRINT [words]

@!	Displays helpful-ish debug info, including version, vault hooks, scripts, enable status, etc
	Must be run by a player. I recommend making a /debug command to run this.

Script Functions

@CALL	Runs another script from within a script.
	Usage: @CALL [FILE:SCRIPT]
	FILE is the filename without the ~~.script.yml~~ extension that the script is in. SCRIPT is the name of the script to run
	Example: @CALL myscriptfile:spawnzombie

@EXIT	Exits the script.
	Usage: @EXIT

@PAUSE	Pauses the scripts execution. This does not pause the trigger, only the script. You may use decimal values or whole numbers 2.5, 1.3, 0.25 or 2, 3
	Usage: @PAUSE [SECONDS]

@COOLDOWN	This will set a cooldown on the trigger this script is executed on. The trigger will not be able to be activated by any player for the CoolDown time in seconds. This does not stop the script from running this time, it only keeps it from being triggerd agian. It is very important if you are going to use the @COOLDOWN that you put it as close to the beginning of the script as possible. Especially before any @PAUSE in the script.
	Usage: @COOLDOWN [SECONDS]
	Example: @COOLDOWN 10.5

@CMD	Execute a command as the player. Player must have permission for the command
	Usage: @CMD [COMMAND]
	Example: @CMD heal

@CMDOP	Execute a command as OP. This is good if you want to avoid permissions
	Usage: @CMDOP [COMMAND]
	Example: @CMDOP i dsword 1

@CMDCON	Execute a command as as if it were typed in the server console. This is good if OP will not get the job done but ony works with commands that can be executed from the console
	Usage: @CMDCON [CONSOLCOMMAND]
	Example: @CMDCON give <playername> dsword 1

@CANCEL [true / false]	Place this on the FIRST LINE of most events and it will prevent or allow the event from happening

World Editing

@SETBLOCK	Sets the block at location to the specified block ID:Data
@SETBLOCKSAFE	Sets the block safely for spigot servers
	Usage: @SETBLOCK [BLOCKID:DATA] [LOCATION]

@TOGGLEBLOCK	Toggles the block selected on or off
	Usage: @TOGGLEBLOCK [BLOCKID:DATA] [LOCATION]
	Example: @TOGGLEBLOCK 35:4 231,69,177

@DROPITEM	Drop an item anywhere. You also may add enchantments.
	Usage: @DROPITEM [ITEMNAME] [QUANTITY] [ENCHANTMENTS] [LOCATION]
	ENCHANTMENTS must be NONE or Enchantment:Level,Enchantment:Level...
	Example @DROPITEM Iron_Sword 1 Sharpness:2,BaneOfArthropods:1 <triggerloc>
	Example @DROPITEM Dirt 1 NONE 231,65,-122
	Example of Item Names: Dirt, Raw_Beef, Wood_Stairs, Chest, Redstone_Wire,Chainmail_Chestplate, Diamond_Helmet
	Example of Enchantment Names( no UnderScores): AquaAffinity, FeatherFalling, Protection, ProjectileProtection
	For a list of enchantments http:www.minecraftwiki.net/wiki/Enchanting
	It's up to you to know which enchantments can go on what items and what the max level is. Any level set higher than the max for an enchantment will be set to its max for you.

@SIGNTEXT	Change the text on a sign. You can use &0-&f, &l-&r color codes
	Usage: @SIGNTEXT [LOCATION] [LINE] [TEXT]
	Location is optional. You will be asked to click the sign if location is not provided.
	You can clear a line with %c.

@FALLINGBLOCK	Makes a block fall like sand.
	Usage: @FALLINGBLOCK [material] [location]
	Example: @FALLINGBLOCK cobblestone 40,40,40

@ENTITY	Spawn an entity. QUANTITY is the number of entitie to spawn. 20 is the max with the exception of EXPORB, QUANTITY is the amount of experience the Orb is worth.
	Usage: @ENTITY [ENTITY] [QUANTITY] [LOCATION]
	BLAZE, CAVE_SPIDER, CHICKEN, COW, CREEPER, ENDER_DRAGON, ENDERMAN, EXPERIENCE_ORB, GHAST, GIANT, IRON_GOLEM, MAGMA_CUBE, MUSHROOM_COW, PIG, PIG_ZOMBIE, SHEEP, SILVERFISH, SKELETON, SLIME, SNOWMAN, SPIDER, SQUID, VILLAGER, FARMER, BLACKSMITH, BUTCHER, LIBRARIAN, PRIEST, WOLF, ZOMBIE
	Example: @ENTITY PRIEST 1 <triggerloc>

Player Modification

@TP	Teleport triggering player to LOCATION. For best results use /vt setloc OBJ VAR in the game to save a location and orientation to an $Obj.Var and use this for the Location argument
	Usage: @TP [LOCATION]
	Example: @TP $loc.farm

@WORLDTP	Teleport to a different world at your current coords.
	Usage: @WORLDTP [player] [world]

@OPENINV	Opens an inventory from your InventoryTriggers.yml file to use as a gui
	Usage: @OPENINV [name]
	Example: @OPENINV teleportInventory

@CLOSEINV	Force-closes someone's inventory
	Usage: @CLOSEINV [player]

@MODIFYPLAYER	A whole lot of commands that should allow you to drop some more plugins. #vtmasterrace
	Usage: @MODIFYPLAYER [player] [modification] [value]
	Example: @MODIFYPLAYER <playername> HEALTH 20
	Info: You can use two underscores to indicate a space for display names and other inputs
	List of modifications:
	HEALTH number
	FOOD number
	SATURATION number
	EXP and XP number
	WALKSPEED number, please note over 1 is insanely fast; use 0.2 for a little bit of boost.
	FLYSPEED number, please note over 1 is insanely fast; use 0.2 for a little bit of boost.
	DISPLAYNAME string, you can use color codes like &a
	LISTNAME string, you can use colors codes like &a
	FLYING boolean
	GAMEMODE string, use creative, survival, or adventure
	MAXHEALTH number
	HELDITEM string, use a valid material, like cobblestone
	HELDITEM:MATERIAL string, this keeps the item data and just swaps the material type
	HELDITEM:ID string, same as above but in ID form
	HELDITEM:META number, used to change the type of something such as white wool to pink wool
	HELDITEM:AMOUNT number up to 64
	HELDITEM:ENCHANT string, use a valid enchant like damage_all. This will always be a level 1 enchant
	HELDITEM:DISPLAYNAME string, keeps data but changes the item name. Color codes work.
	HELDITEM:LORE:SET string, sets the lore to that exactly.
	HELDITEM:LORE:ADD string, must already have lore to add to
	HELDITEM:LORE:REMOVE string, kills all lore
	HIDDEN boolean, hides (or unhides) the player from the server (invisible and in tab)
	BANNED boolean, this requires advanced mode, and won't kick the player from the server
	OPERATOR boolean, this required advanced mode and puts a message in console

Effects

@FIREWORK	Effect - fireworks. COLOR is the firework color. TYPE is what kind of firework.
	Colors: red, blue, aqua, black, fuchsia, gray, green, lime, maroon, navy, olive, orange, purple, silver, teal, white, yellow, random
	Types: ball, ball_large, burst, creeper, star, random
	Usage: @FIREWORK [COLOR] [TYPE] [LOCATION]
	Example: @FIREWORK red burst <playerloc>

@SMOKE	Effect - smoke. VOLUME is an integer representing the amount. 5 is the max
	Usage: @SMOKE [VOLUME] [LOCATION]

@PARTICLE	Convert any material into a particle effect.
	Usage: @PARTICLE [material] [location]
	Example: @PARTICLE cobblestone <playerloc>

@SOUND	Play a sound effect at the given location
	Usage: @SOUND [SOUNDEFFECT] [LOCATION]
	BLAZE_SHOOT, BOW_FIRE, CLICK1, CLICK2, DOOR_TOGGLE, EXTINGUISH, GHAST_SHOOT, GHAST_SHRIEK, STEP_SOUND, ZOMBIE_CHEW_IRON_DOOR, ZOMBIE_CHEW_WOODEN_DOOR, ZOMBIE_DESTROY_DOOR
	Example: @SOUND ZOMBIE_DESTROY_DOOR <triggerloc>

@SOUNDEX	This will let you play all those extra sounds and change the volume and pitch of the sound.
	Usage: @SOUNDEX [sound] [volume] [pitch] [location]
	sound is the name of the sound to play. See Sounds for a list
	volume is a value between 0.0 and 1.0
	pitch is a value between 0.5 and 2.0
	location is the location the sound will come from. If you do not put a location then you will be prompted to click on a location and it will be added for you.

@SETVELOCITY	Push a player in a direction!
	Usage: @SETVELOCITY [player] [x] [y] [z] the numbers for x,y,z are how powerful in that direction to push
	Example: @SETVELOCITY <playername> 0 2 0 this would give about 20 blocks of push

@FLAMES	Effect - flames. VOLUME an integer representing the amount. 5 is the max
	Usage: @FLAMES [VOLUME] [LOCATION]
	Example: @FLAMES 3 <playerloc>

@POOF	Effect - Poof of smoke emanating outward. VOLUME an integer representing the amount. 5 is the max
	Usage: @POOF [VOLUME] [LOCATION]

@LIGHTNING	Creates lightning strike at location, CauseDamage = true `\|` false
	Usage: @LIGHTNING [CAUSEDAMAGE] [LOCATION]
	Example: @LIGHTNING true <triggerloc>

@EXPLOSION	Creates an explosion at location. POWER=0.0 to 4.0 A power of 0.0 will give effect but no damage.
	Usage: @EXPLOSION [POWER] [LOCATION]
	Example: @EXPLOSION 2.5 89,78,211

Fork	Don't tell Lex about this!

Variable collecting

@GETBLOCK	Save the block at location in an $Object.Var
	Usage: @GETBLOCK [OBJ.VAR] [LOCATION]
	With this you can save a block before you change it and then you can change it back to what it was before
	Example: @GETBLOCK $<this>.block <triggerloc>

@GETENTITYCOUNT	Get the count of nearby Entities
	Usage: @GETENTITYCOUNT [OBJECTVARIABLE] [ENTITY] [RADIUS]
	OBJECTVARIABLE - An $object.variable to save the count in and use it later.
	ENTITY - The entity you want to get the count of ZOMBIE, CREEPER, COW PLAYER and so on...
	RADIUS - The radius in blocks from the triggering player to check for entities
	Example: @GETENTITYCOUNT $<playername>.zombieCount ZOMBIE 8

@GETLIGHT	Saves the light level at Location to the $Obj.Var for later use
	Usage: @GETLIGHT [OBJ.VAR] [LOCATION]
	This gets the light level (0 to 15) at the Location reguardless if it is sun, moon or lamp light. Keep in mind that if the location is a solid block this will return 0
	Example: @GETLIGHT $<this>.light <playerloc>

Dynamic Variable Commands

This section contains commands for manipulating Dynamic Object.Variables

@SETINT	Sets an integer variable.
	Usage: @SETINT [$OBJECT.VARIABLE] [INTEGERVALUE]

@ADDINT	Adds a value to an integer variable.
	Usage: @ADDINT [$OBJECT.VARIABLE] [INTEGERVALUE]

@SUBINT	Subtracts from an integer variable.
	Usage: @SUBINT [$OBJECT.VARIABLE] [INTEGERVALUE]

@MULINT	Multiply $Obj.Var by INT
	Usage: @MULINT [$OBJECT.VAR] [INTVALUE]

@DIVINT	Divide $Obj.Var by INT
	Usage: @DIVINT [$OBJECT.VAR] [INTVALUE]

@SETBOOL	Sets a Boolean variable.
	Usage: @SETBOOL [$OBJECT.VARIABLE] [true`\|`false]

@SETSTR	Sets a string variable with the given text.
	Usage: @SETSTR [$OBJECT.VARIABLE] [TEXT]

@ADDSTR	Add text to the end of an $Obj.Var String
	Usage: @ADDSTR [$OBJECT.VAR] [TEXT]
	TEXT is the string to add to the end of an existing $Obj.Var of type string

@GETSTRLEN	Gets the length of a text String and stores it in an $Obj.Var
	Usage: @GETSTRLEN [$OBJ.VAR] [STRINGTOTEST]

@DELVAR	Deletes an $Object.Variable from memory. This helps keep memory free of ones you don't need to stay permanent such as temporary variables
	Usage: @DELVAR [i`\|s\|`b] [$OBJECT.VARIABLE] - i=int s=str b=bool

@DELOBJ	Deletes an $Object from memory. This helps keep memory free of ones you don't need to stay permanent such as temporary objects
	Usage: @DELOBJ $object

@STRBUILD	Builds a string with the given critera.
	@STRBUILD $obj.var <line> <message>
	Places the message args after line into $objvar
	@STRBUILD $obj.var 2 Hello there how are you doing would say how are you doing

MySQL

This section contains MySQL Info

@MYSQL	Enter your database information in the MYSQL.yml file. You can then use normal java mysql commands.
	@MYSQL @obj.var <statement>
	The result will be placed in @obj.var for your viewing pleasure.
	Example: @MYSQL select * from users;
	Please note that I'm not responsible for telling you how to use MYSQL syntax, please look it up somewhere.
	Also I've not tested making new databases. Worst case you can just make one manually.

Array Lists

Sort things into a list. Related Commands:

@ADDLIST	@obj.var something
@REMLIST	@obj.var something
@DELLIST	@obj.var
	@ADDLIST @player.list
	@ADDLIST @player.list WinneonSword
	@PLAYER @player.list[1]
	You would see WinneonSword because 1 is the second entry in a list.
	Now, if you want to remove WinneonSword from the list...
	@REMLIST @player.list WinneonSword
	@PLAYER @player.list[0]
	We can pull Hugh_Jasses with the index of 0 now. Lastly, to see how many things are in a list...
	@PLAYER @player.list
	If you do not specify an index, it will display how many items are in there. This would return 1
	You can use variable names for the index as well, such as...
	@PLAYER @player.list[<var:$counter.variable>]
	This only works with <var:> surrounding the variable.
	Also check if something is in the list with @IF @player.list ?= WinneonSword

@VTSystem.OnlinePlayers	Creates an arraylist of every player's name who is online.
@VTSystem.OnlineUUIDs	Same as above but lists the UUIDs instead.

Conditional Testing

This is the logic section. You control the flow of logic in the script.

@IF	Starts a conditional if block. Test two values. If the statement evaluates to true, the script enters the if block and executes each line until it reaches an @ELSE or @ENDIF. If it evaluates to false it skips each line until it reaches an @ELSE or @ENDIF.
	Usage: @IF [i`\|b\|s\|si] [$VARIABLE\|CONSTANT] [=\|!=\|>\|<\|<=\|>=\?=] [$VARIABLE\|CONSTANT\|true\|false`]
	i= Integer test
	b= Boolean test
	s= String test
	si=String Case Insensative test
	Example: @IF i $<playername>.logins >= 30
	Example: @IF s <playername> = LexLaiden
	Example: ?= checks if a string contains a string
	Example: @IF si $object.var ?= red If this object contains the word red...
	Example: @IF s $obj.var = null Checks if it's empty.

@OR	Testing against the previous evaluation. @OR and @AND can only be placed immediately after an @IF, @OR or @AND line.
	Usage: Same as above.

@AND	Testing against the previous evaluation.
	Usage: Same as above.

@ELSE	Start an else block.
	Usage: @ELSE

@ENDIF	End the current If block
	Usage: @ENDIF

In the game you can add a script line to a trigger like so.
/vtclick @SETBLOCK 35:9
You will be asked to click a location.

If you want to edit the YML files by hand you may use tabs or spaces Only at the beginning of a script line to indent your @IF blocks for readability. Don't forget that each @IF block must have a matching @ENDIF

'// lines that start with // are comments.'
'// Start by setting a cooldown so no one can use trigger for 15 sec'
'@COOLDOWN 15'
'// check to see if they have completed the quest'
'@IF b $<playername>.Quest1_Complete = true'
'    @PLAYER &9<playername> You have completed the first quest.'
'    @IF i <itemid> != 368'
'        @PLAYER You should have retrieved the Ender Pearl.'
'        @PLAYER Click this block with the pearl.'
'    @ELSE'
'        @PLAYER You may proceed. Hurry!'
'        @TOGGLEBLOCK 76:1 $Hidden.RedTorchLoc'
'        // pause for 10 1/2 seconds'
'        @PAUSE 10.5'
'        @TOGGLEBLOCK 76:1 $Hidden.RedTorchLoc'
'    @ENDIF'
'@ELSE'
'    @PLAYER You should venture forth to the Barons Keep'
'    @PLAYER before you proceed down this tunnel.'
'    @SOUND GHAST_SHRIEK 231,43,-118'
'    @ENTITY GHAST 2 231,43,-120'
'@ENDIF'

@SWITCH and @CASE	It's like @IF, except better.
	Usage: @SWITCH [type] [variable] You can use s, i, and b
	Example:

'@SWITCH s $object.variable'
'    @CASE red'
'        @PLAYER The object is red!'
'    @CASE blue green orange purple'
'        @PLAYER The object is blue, green, orange, or purple!'
'@ENDSWITCH'

	All switches must end with an @ENDSWITCH
	There is no @ENDCASE, as a @CASE marks the end of the previous one.

Loops

@LOOP	Start a loop block. All lines after @LOOP up to the matching @ENDLOOP will be exicuted count times. Each @LOOP MUST have a matching @ENDLOOP and you cannot criss cross @IF blocks.
	Usage: @LOOP [COUNT]

@BREAKLOOP	This will allow you to break from a @LOOP block. You would use it in an @IF test inside of a Loop block.
	Usage: @BREAKLOOP
	Example:
	@IF b $some.var = true
	@BREAKLOOP
	@ENDIF

@ENDLOOP	End of a loop block.
	Usage: @ENDLOOP

@WHILE	This is a contitional loop and give you ability to loop based on testing
	Usage: @WHILE `[i\|b\|s\|si] [VALUE] [=\|!=\|>\|<\|>=\|<=]` [VALUE]
@ENDWHILE	This ends a while loop block
	Usage: @ENDWHILE

@LOOP and @WHILE are turned off by default. Read http://dev.bukkit.org/server-mods/variabletriggers/pages/about-loops/ to learn how to turn on loops

note: you only need to enclose script lines in single quotes if you are manually editing the YML files. If you are creating scripts in the game you must NOT enclose the script lines with single quotes. This is done for you by the system.

To Getting Started

To Index Page

Bukkit

VariableTriggers

Bukkit Plugins

Pages

docs/Script Commands

Table of Contents