Got a question that the wiki doesn't answer? Ask on the forum (preferred), or join us on IRC.



From Wiki
Jump to: navigation, search


3.3.1 is a culmination of almost 4 years of work. There are hundreds of new functions, and tons of bugfixes and new functionality.

Update Breakages

Extensions that worked previously can now only work with the latest builds. All extensions will need to be updated.

New feature overview

  • Closures were added. Many methods require a closure, but you can use closures in custom code as well.
  • Smart Strings. Variable interpolation in strings quoted with double quotes, "@likeThis".
  • Local Packages. Group your code into logical batches.
  • MSLP files. Use the MSLP maker cmdline tool to distribute your code in a single file.
  • Operators. Instead of using add(2, 2), use 2 + 2.
  • Script optimization. Many backend changes have been made to make your scripts run even faster, with no effort on your part
  • Brace Syntax. Use braces in more places: if(@condition){ }, for instance. Makes your code much easier to read.
  • Switch statements. Rewrite large chains of if/else if into the better looking switch statement.
  • while/dowhile loops. Some loops can be more easily written using these mechanism.
  • SQL. Connect to MySQL, SQLite, and PostgreSQL databases.
  • Cmdline. Like MethodScript? Use it anywhere! Run scripts from the command line, and do some neat cmdline only things.
  • Persistence Network. Store your data in lots of different formats, not just the built in serialization format.
  • PN Viewer UI. View your data using a GUI, instead of messing around with command line stuff. Connect to a remote server even, so you can run the GUI on your desktop, and manage your headless server.
  • Code Profiler. Profile your code, to find where the slow spots are.
  • Byte Arrays. Manage bits and bytes.
  • Extensions. Not officially supported yet, but generally quite useful. Add your own functions, or get extensions from other people to extend MethodScript.
  • HTTP functions. Connect to a website, and download information from the web, then use it in your application. Allows for SOAP, REST and other web based connections
  • Removal of PermGen requirements. No longer will you need to edit your PermGen settings, a new backend is now in use.
  • Shell functions. Run other executables on the system.
  • Typing. typeof() instanceof() and other methods have been added to allow you to more easily manage your data types.
  • // is a line comment. Use the traditional C-style line comment in your code.
  • function_exists/event_exists/compile_error. Using these special functions, make your code work with different versions of MethodScript.
  • 0b and 0x. Write hex and binary numbers directly in code. 0xF == 0b1111 == 15.
  • Well definied array iteration. When adding and removing values while iterating arrays in foreach, they do what you want in more cases.
  • Email support. Easily send an email from your scripts with the email() function.
  • Type hinting. Make sure your variables pick a type and stick with it. Type hinting is now implemented, and will eventually be upgraded into strong typing. int @int = 'not an int'; is now an error.
  • Fully supported try/catch blocks. Catch multiple exception types and do different things for each. Finally clauses also supported.

API Additions

407 new functions have been added:

add_recipe(), add_to_inventory(), all_entities(), array_deep_clone(), array_every(), array_filter(), array_indexes(), array_index(), array_insert(), array_iterate(), array_last_index(), array_map(), array_rand(), array_reduce_right(), array_reduce(), array_remove_values(), array_reverse(), array_shallow_clone(), array_some(), array_sort_async(), array_sort(), array_unique(), associative_array(), async_read(), ba_as_array(), ba_get_bytes(), ba_get_byte(), ba_get_char(), ba_get_double(), ba_get_float(), ba_get_int(), ba_get_long(), ba_get_short(), ba_get_string(), ba_is_little_endian(), ba_put_bytes(), ba_put_byte(), ba_put_char(), ba_put_double(), ba_put_float(), ba_put_int(), ba_put_long(), ba_put_short(), ba_put_string(), ba_rewind(), ba_set_little_endian(), base64_decode(), base64_encode(), bcrypt(), bit_xor(), build_date(), byte_array(), call_proc_array(), can_pickup_items(), capture_runas(), cd(), char_from_unicode(), check_bcrypt(), clear_commands(), clear_cron(), clear_recipes(), clear_screen(), clear_task(), close_pinv(), colorize(), comp_read(), compile_error(), create_objective(), create_scoreboard(), create_team(), create_world(), cslice(), damage_entity(), dowhile(), dump_threads(), email(), enchantment_list(), engine_build_date(), entities_in_radius(), entity_air(), entity_can_see(), entity_exists(), entity_fall_distance(), entity_grounded(), entity_id(), entity_line_of_sight(), entity_loc(), entity_max_air(), entity_onfire(), entity_remove(), entity_spec(), entity_type(), entity_uuid(), entity_velocity(), event_exists(), execute(), exit(), explosion(), extension_exists(), extension_info(), fake_incoming_plugin_message(), file_resolve(), file_size(), foreachelse(), forelse(), function_exists(), generate_tree(), get_aliases(), get_all_recipes(), get_armor_color(), get_art_at(), get_banned_players(), get_biome(), get_block_command(), get_block_info(), get_block_power(), get_chunk_loc(), get_command_block_name(), get_command_block(), get_commands(), get_difficulty(), get_entity_age(), get_entity_breedable(), get_entity_max_speed(), get_entity_persistence(), get_entity_rider(), get_entity_vehicle(), get_env(), get_equipment_droprates(), get_events(), get_functions(), get_gamerule(), get_highest_block_at(), get_inventory_item(), get_inventory_size(), get_inventory_type(), get_inventory(), get_ip_bans(), get_itemmeta(), get_leashholder(), get_light_at(), get_list_name(), get_loaded_chunks(), get_locales(), get_max_health(), get_metadata(), get_mob_age(), get_mob_effects(), get_mob_equipment(), get_mob_name(), get_name_visible(), get_objectives(), get_offline_players(), get_peffect(), get_pflyspeed(), get_pitch(), get_player_from_entity_id(), get_procedures(), get_projectile_bounce(), get_projectile_shooter(), get_pscoreboard(), get_pscore(), get_pvp(), get_pwalkspeed(), get_recipe_for(), get_registered_channels(), get_scoreboards(), get_script_environment(), get_server_info(), get_spawner_type(), get_teams(), get_temperature(), get_terminal_width(), get_whitelisted_players(), get_worlds(), get_yaw(), has_bind(), has_metadata(), has_storm(), has_thunder(), heap_dump(), hmac_md5(), hmac_sha1(), hmac_sha256(), http_clear_session_cookies(), http_request(), iclosure(), ini_decode(), ini_encode(), instanceof(), is_alias(), is_block_powered(), is_bytearray(), is_channel_registered(), is_closure(), is_entity_living(), is_leather_armor(), is_number(), is_slime_chunk(), is_stringable(), is_string(), json_decode(), json_encode(), launch_firework(), levenshtein(), load_chunk(), location_shift(), logarithm(), lsprintf(), ls(), marquee_stop(), marquee(), material_info(), math_const(), monitor_redstone(), neg(), noop(), parse_date(), parse_int(), pbed_location(), penchanting(), penderchest(), pfirst_played(), pget_time(), pgive_enderchest_item(), phas_flight(), phas_played(), phas_storm(), pheld_slot(), phunger(), pinv_open(), plast_played(), play_entity_effect(), play_named_sound(), play_note(), play_sound(), players_in_radius(), postdec(), postinc(), preset_time(), print_err(), print_out(), prompt_char(), prompt_line(), prompt_pass(), psaturation(), psend_block_change(), psend_sign_text(), psetop(), pspectator_target(), ptake_enderchest_item(), ptarget_space(), puuid(), pvehicle_leave(), pvehicle(), pwd(), pworkbench(), query_async(), query(), queue_clear(), queue_delay_front(), queue_delay(), queue_push_front(), queue_push(), queue_remove_front(), queue_remove(), queue_running(), read_binary(), read_gzip_binary(), read_pipe_input(), ref_equals(), reflect_docs(), reflect_pull(), reflect_value_source(), reg_escape(), regen_chunk(), register_channel(), register_command(), remove_metadata(), remove_objective(), remove_scoreboard(), remove_team(), res_create_resource(), res_free_resource(), reset_all_pscores(), reset_recipes(), run_cmd(), save_players(), save_world(), send_plugin_message(), send_resourcepack(), send_texturepack(), sequals_ic(), set_armor_color(), set_art_at(), set_biome(), set_block_command(), set_can_pickup_items(), set_cmdline_prompt(), set_command_block_name(), set_cron(), set_difficulty(), set_entity_age(), set_entity_air(), set_entity_breedable(), set_entity_fall_distance(), set_entity_loc(), set_entity_max_air(), set_entity_max_speed(), set_entity_onfire(), set_entity_persistence(), set_entity_rider(), set_entity_spec(), set_entity_velocity(), set_env(), set_equipment_droprates(), set_executor(), set_gamerule(), set_interval(), set_inventory_item(), set_inventory(), set_ip_banned(), set_itemmeta(), set_leashholder(), set_list_name(), set_max_health(), set_metadata(), set_mob_age(), set_mob_effect(), set_mob_equipment(), set_mob_name(), set_name_visible(), set_objective_display(), set_pbed_location(), set_penderchest(), set_pflight(), set_pflying(), set_pflyspeed(), set_pheld_slot(), set_phunger(), set_projectile_bounce(), set_projectile_shooter(), set_psaturation(), set_pscoreboard(), set_pscore(), set_pspectator_target(), set_pstorm(), set_ptime(), set_pvelocity(), set_pvp(), set_pwalkspeed(), set_spawner_type(), set_spawn(), set_tabcompleter(), set_team_display(), set_team_options(), set_thunder(), set_timeout(), set_uncaught_exception_handler(), sha256(), shell_adv(), shell(), shoot_projectile(), show_enderchest(), shutdown_server(), simple_date(), snequals(), spawn_entity(), spawn_falling_block(), split(), sprintf(), string_append(), string_from_bytes(), string_get_bytes(), string_position(), sudo(), sys_beep(), sys_err(), sys_out(), sys_properties(), take_from_inventory(), team_add_player(), team_remove_player(), to_radix(), trace(), triml(), trimr(), typeof(), unicode_from_char(), unload_chunk(), unload_world(), unregister_channel(), unregister_command(), unsafe_query(), url_decode(), url_encode(), user(), while(), world_info(), x_get_current_thread(), x_new_thread(), x_run_on_main_thread_later(), x_run_on_main_thread_now(), xml_read(), yml_decode(), and yml_encode()

Event API additions

76 events were added.

creature_spawn, block_grow, food_level_changed, world_save, entity_interact, block_dispense, entity_change_block, item_despawn, inventory_click, vehicle_move, block_break, exp_change, note_play, shutdown, cmdline_prompt_input, player_interact_at_entity, player_leave_bed, block_ignite, world_load, item_pre_enchant, entity_death, item_enchant, world_unload, projectile_hit, item_held, player_quit, player_move, item_drop, tree_grow, weather_change, entity_damage_player, entity_damage, block_place, world_changed, player_toggle_sneak, projectile_launch, player_fish, server_ping, entity_explode, player_prelogin, inventory_close, lightning_strike, player_teleport, redstone_changed, inventory_drag, target_player, player_enter_bed, item_pickup, player_interact_entity, block_burn, vehicle_leave, vehicle_collide, thunder_change, gamemode_change, async_player_chat, item_pre_craft, piston_retract, player_toggle_flight, tab_complete_chat, pressure_plate_activated, inventory_open, player_login, vehicle_enter, player_command, player_consume, player_kick, tab_complete_command, sign_changed, piston_extend, entity_enter_portal, player_portal_travel, player_toggle_sprint, item_spawn, hanging_break, book_edited, and plugin_message_received


3.3.0 is a massive update that contains a huge number of new features. There are a few things that are incompatible with the previous version, so you should carefully read this release notice before upgrading. If you are starting from scratch, there are (of course) no incompatibilities.

Update Breakages

  • include/read now require paths that are relative to the location of the current file. This should be an easy fix.
  • Your persistance database is in the wrong format. Unlike previous versions, you do not need to delete the database, you simply need to upgrade it. (Unless you're upgrading from before 3.2.0, in which case you still do need to delete the persistance.ser file, and then you're set.) If you have not used user aliases or persistance in the past, this step is unnecessary. Rename/copy/symlink your bukkit jar to bukkit.jar for this to work. From a command prompt, change to the plugins directory and run java -jar CommandHelper.jar --manager. This will launch the Data Manager, at which point you can run the upgrade command. Once this is complete, your data is now converted to the new format! Do not run the data manager while your server is up. In lieu of this, you may also simply delete your persistance.ser file, in which case all data will be lost, but it will re-create the db in the correct format in the future, without any interaction from you. Be sure to check out the other features in the data manager while you're there!
  • is_* (is_null(), is_integer(), etc) functions are slightly altered. Most people weren't using these functions, but if you were, you will want to check the API for information on the changes to this function.
  • pinv() and set_pinv() take different formatted arguments. Check the API for the new usage.
  • play-dirty mode is currently broken due to the new event system implementation. This will be fixed at a later date, but you may not need it any more, since plugins have all been updated now.

New Feature Overview

  • Colors work in the terminal now. The exception is if you're on a windows machine, in which case, no colors for you :( sorry. Also, CH has a cool new splash screen (you can disable it in the preferences).
  • Data Manager - You can now view the persistance data much easier, thanks to the data manager. Be sure to explore all the options. Read up on it at the page on the data manager.
  • Abstraction layer - While you won't see this directly, know that it's much easier to move CH from server type to server type, should bukkit or whatever other server mod become obsolete. This means that CH should live on past server mods, with your scripts safe from the changes!
  • Namespaces in persistance, and improved performance in persistance - Persistance is now much more efficient. In addition, namespace support has been implemented. If you namespace your data using periods, you can much more easily manipulate the data that has been stored. Be sure to re-read the API in the Persistance section, as all the functions have new features now.
  • Events added - Events are now here! Read up on the Events overview for basic information relating to all events, and check out the Event API for details on specific events, as well as what events are available. This list will continue to grow as more events are added!
  • ifelse and switch - Now it is much easier to chain if statements. Check out the wiki page on logic for more information.
  • Arrays are associative - Now you can store a value in an array not only with a numeric index, but you can also use strings! Many functions now use this feature, since it's much easier to read and use, but you need to be familiar with the changes for them to make sense. Check out the additional section in the wiki page on arrays
  • bitwise operations - binary operations! Check the API page for details.
  • Basic crypto functions - If you need to hash things, this is now possible.
  • import/export - Import and export work like the persistance functions, except they are in-memory only, and won't survive past server restarts (or /reloadaliases, for that matter). There are two modes of operation, so read the API carefully if you use these functions.
  • More defined data types, in addition to casting and converting functions - Data types were loosely defined before. Now the definition is well defined, and there are functions to help you manipulate this data.
  • Enchantment api - You can now control enchantments in a player's inventory
  • Sign api - Change the text of signs with functions! This function allows you to colorize the text on the sign as well, when used in combination with the color() function.
  • More math functions - Just about every math operation you could need is now implemented. Be sure to also check out the very cool expr() function, which should simplify complicated math formulas.
  • Basic entity control - You can now control entity health and tame wolves. This is just the first phase of more complex entity controls.
  • scriptas and has_permission - scriptas() allows you to run scripts as another player, similarly to how you can run a command as another player with runas(). has_permission() allows you to dynamically check to see if a player has an arbitrary permission or not.
  • data_name (reverse data_values)
  • More inventory controls - Previous versions had pinv and set_pinv, and that was all the control you needed to do whatever you like, but it is unwieldy, and complicated to use. These functions arguments have changed as well, but you can now use a few other functions to more easily do things: phas_item, pitem_slot, pgive_item, ptake_item. Check out the API for more information for each of these functions.
  • World time controls - Control the time in a world with the new world time functions.

API additions

Here's a full list of all the new functions. Check out the API for details on each:


  • Player's pitch and yaw (the way they're facing) is preserved when using set_ploc
  • Fixed a bug when dealing with offline players in pinfo (as well as a few other functions)
  • substr() now works properly if the last argument is left off
  • When using an ivar as the second parameter in assign(), it works properly now.
  • Added interpreter mode!
  • Added user defined procedures
  • read() and include() are subject to the base-dir restriction now
  • # comments work even if they aren't the first character on the line. C style block comments are also available. /* */
  • Commands can be run from the console. If the command doesn't make sense to run without a player, the command should fail gracefully.
  • Added include and procedures. See this page for more details.
  • Potion Effects can now be accessed with set_peffect. See the guide on the minecraft wiki for ID numbers and other information
  • Added case-sensitive option to make it possible to toggle command matching being case sensitive or not
  • Arrays are much more flexible now
  • The \u escape sequence is implemented in the lexer. This allows insertion of arbitrary unicode characters into scripts.
  • The WG/WE series of functions are implemented now
  • Added functions: sqrt, include, proc, return, pinv, set_pinv, min, max, is_proc, call_proc, pexp/set_pexp (experimental), ptexp/set_ptexp (experimental), plevel/set_plevel (experimental), pmode/set_pmode, set_peffect (requires CraftBukkit), array_resize, range, Economy Functions, call_alias, item_drop, set_phealth, equals_ic, sk_all_regions, sk_pos1, sk_pos2, sk_region_info, sk_region_overlaps


  • Added exception handling, and fixed more bugs with command matching and

optional variables. Also added more advanced permission syntax for commands.

  • Added functions: set_display_name, reset_display_name, try, array_index_exists,

is_array, is_boolean, is_double, is_integer, is_null, is_string, substr, to_lower, to_upper, length, throw

  • msg() and all other applicable Echoes functions now handle newlines and linebreaks properly. Besides being able to use a \n character to mean a newline character, word wrapping now occurs at word boundaries instead of arbitrarily. Thanks to Reil for the code to do that! Also, if a file is read in with read(), and it has newlines in it, newline characters are passed through to the other functions properly.
  • Permissions handling just got easier. In addition to being able to label a command, and giving that group/user permission to commandhelper.alias.label, you can give groups permissions to certain commands by doing:
~admin:/adminOnlyCommand = msg('This is an admin only command')

In addition, you can give multiple groups permission, in one go, like this:

~admin/mods:/adminOrModCommand = msg('This is an admin or mods command')

Further, you can revoke permissions by putting a dash in front, like so:

~-default:/normallyAbleToUseCommand = ...

Note that permissions take priority from left to right. So, say that a user is in the 'mods' and 'builder' groups. If the setup were in this order: ~mods/-builder, then the user would have permission, but if it were ~-builder/mods, they would not. If the user is not in one of the listed groups, that group name is ignored.

  • Checking that you are passing the correct number of arguments to a function is now done at compile time. This will potentially help reduce the numbers of errors in a script.


  • Fixed a bug where no argument functions in the root of the command would give a compile error.


  • Added several new functions, including eval, set_ploc, time, nano_time, break, continue, get_worlds, pworld, pinfo, and kick. Also, reorganized the source code, and made it so that if one command would cause a compiler error, the entire script won't be affected, but just the one command. Also, concatenation automatically happens now, the g() function is no longer necessary. Debug mode now outputs what real command is being run, if debug mode is on. It is now possible to define the location of your config file, in the preferences.txt file. See the upgrade notices for information about upgrading your scripts from 3.0.2 to 3.1.0.
  • Compiler re-organized and modified. The g() function is no longer necessary, but is still defined, so scripts will remain backwards compatible. Also, scripts with compiler errors will most likely only break the individual command that has the error, the entire script will no longer fail. Of course if the compiler can't determine where the end of the command is (for instance a missing multiline end symbol) more of the script will fail. The sconcat() function is no longer necessary. Let's look at the following code:
/cmd = if(boolean, /run this command, /else run this command)

In previous versions, you had to group the "if" and "else" portions seperately, in this case, you would likely have used sconcat() though g() would have worked. Now, the commas separate the arguments, with tokens between commas automatically being sconcatenated together.

  • The compiler for the scripting language has been broken out of the CommandHelper core. The language itself is now called MScript, and CommandHelper simply hooks into MScript to generate commands to run. This allows me to more easily add other events in the future. Also, in future versions, I will make it so that other plugin authors can hook into MScript to allow their plugins to run MScripts, so that plugin authors can give users more control over the plugin, when applicable. Let's look at the structure of an alias again:
/alias command name and $variables = MScript \ MScript \ MScript

The portions of an alias that are actually part of the MScript language are shown. All other parts are simply identifiers for CommandHelper specifically. While there is still a great deal of integration with the alias engine, the MScript portions can now be used standalone in future applications.

  • eval() functions are now available. As implied, eval() allows arbitrary MScript to be executed.
  • Debug mode now outputs what real command is being run, if debug mode is set to true
  • You can now define the name/location of your config file. In the preferences.txt file, the script-name property defines this value.


  • Added new functions to allow scripts to interact with the environment around the player.


  • Added several new functions, including a foreach loop, and the g function. See the upgrade notices for information about upgrading your scripts from 3.0.0 to 3.0.1.


  • Completly reworked the engine. Essentially a new plugin.


  • Updated to work again.


  • Updated for Bukkit.

Navigation menu