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.