docs/Script Commands

Script Commands

To Getting Started

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.


Messaging and chat commands.

@QUIETPrevents all chat from being displayed on selected player for the number of 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
@CLEARCHATWipes the chat window clean for someone.
Usage: @CLEARCHAT [player]
@BROADCASTBroadcast a message to the whole server. Color codes &a-&f, &1-&9 and Special codes &l &n &o &m &r are welcome.
@PLAYERDisplays 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.
@TELLDisplays 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.
@PRINTPrints 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

@CALLRuns another script from within a 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
@EXITExits the script.
Usage: @EXIT
@PAUSEPauses 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
@COOLDOWNThis 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.
Example: @COOLDOWN 10.5
@CMDExecute a command as the player. Player must have permission for the command
Example: @CMD heal
@CMDOPExecute a command as OP. This is good if you want to avoid permissions
Example: @CMDOP i dsword 1
@CMDCONExecute 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
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

@SETBLOCKSets the block at location to the specified block ID:Data
@SETBLOCKSAFESets the block safely for spigot servers
@TOGGLEBLOCKToggles the block selected on or off
Example: @TOGGLEBLOCK 35:4 231,69,177
@DROPITEMDrop an item anywhere. You also may add enchantments.
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
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.
@SIGNTEXTChange the text on a sign. You can use &0-&f, &l-&r color codes
Location is optional. You will be asked to click the sign if location is not provided.
You can clear a line with %c.
@FALLINGBLOCKMakes a block fall like sand.
Usage: @FALLINGBLOCK [material] [location]
Example: @FALLINGBLOCK cobblestone 40,40,40
@ENTITYSpawn 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.
Example: @ENTITY PRIEST 1 <triggerloc>

Player Modification

@TPTeleport 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
Example: @TP $
@WORLDTPTeleport to a different world at your current coords.
Usage: @WORLDTP [player] [world]
@OPENINVOpens an inventory from your InventoryTriggers.yml file to use as a gui
Usage: @OPENINV [name]
Example: @OPENINV teleportInventory
@CLOSEINVForce-closes someone's inventory
Usage: @CLOSEINV [player]
@MODIFYPLAYERA 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
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
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


@FIREWORKEffect - 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
Example: @FIREWORK red burst <playerloc>
@SMOKEEffect - smoke. VOLUME is an integer representing the amount. 5 is the max
@PARTICLEConvert any material into a particle effect.
Usage: @PARTICLE [material] [location]
Example: @PARTICLE cobblestone <playerloc>
@SOUNDPlay a sound effect at the given location
Example: @SOUND ZOMBIE_DESTROY_DOOR <triggerloc>
@SOUNDEXThis 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.
@SETVELOCITYPush 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
@FLAMESEffect - flames. VOLUME an integer representing the amount. 5 is the max
Example: @FLAMES 3 <playerloc>
@POOFEffect - Poof of smoke emanating outward. VOLUME an integer representing the amount. 5 is the max
@LIGHTNINGCreates lightning strike at location, CauseDamage = true | false
Example: @LIGHTNING true <triggerloc>
@EXPLOSIONCreates an explosion at location. POWER=0.0 to 4.0 A power of 0.0 will give effect but no damage.
Example: @EXPLOSION 2.5 89,78,211
ForkDon't tell Lex about this!

Variable collecting

@GETBLOCKSave the block at location in an $Object.Var
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>
@GETENTITYCOUNTGet the count of nearby Entities
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
@GETLIGHTSaves the light level at Location to the $Obj.Var for later use
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

@SETINTSets an integer variable.
@ADDINTAdds a value to an integer variable.
@SUBINTSubtracts from an integer variable.
@MULINTMultiply $Obj.Var by INT
@DIVINTDivide $Obj.Var by INT
@SETBOOLSets a Boolean variable.
Usage: @SETBOOL [$OBJECT.VARIABLE] [true|false]
@SETSTRSets a string variable with the given text.
@ADDSTRAdd text to the end of an $Obj.Var String
TEXT is the string to add to the end of an existing $Obj.Var of type string
@GETSTRLENGets the length of a text String and stores it in an $Obj.Var
@DELVARDeletes 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
@DELOBJDeletes 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
@STRBUILDBuilds 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


This section contains MySQL Info

@MYSQLEnter 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
@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.OnlinePlayersCreates an arraylist of every player's name who is online.
@VTSystem.OnlineUUIDsSame as above but lists the UUIDs instead.

Conditional Testing

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

@IFStarts 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.
@ORTesting against the previous evaluation. @OR and @AND can only be placed immediately after an @IF, @OR or @AND line.
Usage: Same as above.
@ANDTesting against the previous evaluation.
Usage: Same as above.
@ELSEStart an else block.
Usage: @ELSE
@ENDIFEnd 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'
'// 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'
'    @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'
@SWITCH and @CASEIt's like @IF, except better.
Usage: @SWITCH [type] [variable] You can use s, i, and b
'@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!'
All switches must end with an @ENDSWITCH
There is no @ENDCASE, as a @CASE marks the end of the previous one.


@LOOPStart 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]
@BREAKLOOPThis will allow you to break from a @LOOP block. You would use it in an @IF test inside of a Loop block.
@IF b $some.var = true
@ENDLOOPEnd of a loop block.
@WHILEThis is a contitional loop and give you ability to loop based on testing
Usage: @WHILE [i|b|s|si] [VALUE] [=|!=|>|<|>=|<=] [VALUE]
@ENDWHILEThis ends a while loop block

@LOOP and @WHILE are turned off by default. Read 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