From d169f492de75cb975b327a74403a9716323f2a37 Mon Sep 17 00:00:00 2001 From: walterhiggins Date: Sat, 8 Oct 2016 12:15:05 +0100 Subject: [PATCH] Updating Young Person's Guide to use SpigotMC and fixed missing/broken events helper calls. --- README.md | 45 +- docs/API-Reference.md | 1121 ++++++++++++++++- ...YoungPersonsGuideToProgrammingMinecraft.md | 170 +-- src/docs/js/generateEventsHelper.js | 10 +- src/docs/templates/ypgpm.md | 166 +-- 5 files changed, 1254 insertions(+), 258 deletions(-) diff --git a/README.md b/README.md index 5f90cb4..752c124 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# Let's begin … +## ScriptCraft - Modding Minecraft with Javascript + [![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/walterhiggins/ScriptCraft?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ScriptCraft lets you write Minecraft Mods using Javascript - a @@ -20,7 +21,7 @@ files in a directory. then [Start Here][cda]. * Watch some [demos][ytpl] of what you can do with ScriptCraft. -This is a simple mod in a file called greet.js in the scriptcraft/plugins directory … +This is a simple mod in a file called greet.js in the scriptcraft/plugins directory: ```javascript function greet( player ) { @@ -53,6 +54,7 @@ following Minecraft Server software: [spigot]: http://www.spigotmc.org/ [gs]: http://www.glowstone.net/ +[cm]: http://canarymod.net/ I recommend using SpigotMC because both CanaryMod and CraftBukkit are no longer being actively developed. The ScriptCraft mod also lets you @@ -71,26 +73,24 @@ Minecraft. [cottage]: https://github.com/walterhiggins/ScriptCraft/tree/master/src/main/js/plugins/drone/contrib/cottage.js [temple]: https://github.com/walterhiggins/ScriptCraft/blob/master/src/main/js/plugins/drone/contrib/temple.js [bukkit]: http://dl.bukkit.org/ -[cm]: http://canarymod.net/ # Prerequisites -* You will need to have Java version 7 or later installed on your - machine. Check the version by typing `java -version` at a command - prompt. - -* You will need to [install SpigotMC][spigot] on your - machine. SpigotMC is a customized version of Minecraft Server that - makes it easy to install plugins and customize Minecraft. You can - [download the SpigotMC server here.][spigotdl] +ScriptCraft is a Minecraft Server Mod which only works with Minecraft +for Personal computers (Windows, Mac and Linux). It does not work with +X-BOX, Playstation or WiiU versions of the game. You will need to have +Java version 7 or later installed. Check the version by typing `java +-version` at a command prompt. # Installation -Before installing ScriptCraft you must first install SpigotMC which is a special version of Minecraft Server that makes it easy to customize the game. +Before installing ScriptCraft you must first install SpigotMC which is +a special version of Minecraft Server that makes it easy to customize +the game. ## Installing and Running SpigotMC -Follow these steps to download and install SpigotMC on your machine. +Follow these steps to download and install SpigotMC. 1. Download Spigot's [BuildTools.jar][spigotdl] 2. Save the BuildTools.jar file to a new directory called spigotmc. @@ -98,8 +98,13 @@ Follow these steps to download and install SpigotMC on your machine. 4. When the build is done, there will be a new file beginning with `spigot` and ending in `.jar` in the spigotmc directory. Run this file by typing `java -jar spigot-1.10.2.jar` (it might not be that exact name - you can list files in the directory by typing `dir` (Windows) or `ls` (Mac and Linux). 5. The server will start up then shut down very shortly afterwards. You'll need to edit a file called `eula.txt` - change `eula=false` to `eula=true` and save the file. 6. Run the `java -jar spigot-1.10.2.jar` command again - this time the server will start up. Shut it down by typing `stop` at the server prompt. -7. Download the [scriptcraft.jar][dl] plugin and save it to the `plugins` directory and restart the server by typing `java -jar spigot-1.10.2.jar`. -9. At the server prompt type `js 1 + 1` and hit enter. The result `2` should be displayed. + +## Installing ScriptCraft + +Follow these steps to download and install ScriptCraft. + +1. Download the [scriptcraft.jar][dl] plugin and save it to the `plugins` directory and restart the server by typing `java -jar spigot-1.10.2.jar`. +2. At the server prompt type `js 1 + 1` and hit enter. The result `2` should be displayed. Congratulations - you've just installed your Custom Minecraft Server and are ready to begin writing your first mod! @@ -116,7 +121,7 @@ username to the ops.txt file in your server directory. Launch the server, then launch the Minecraft client and create a new server connection. The IP address will be `localhost` . Once you've connected to your server and have entered the game, look at a -ground-level block and type … +ground-level block and type: /js up().box( blocks.wool.black, 4, 9, 1 ) @@ -156,12 +161,12 @@ To get started writing your own mod, take a look at some of the Because the SpigotMC API is open, all of the SpigotMC API is accessible via javascript once the ScriptCraft plugin is loaded. There are a couple of useful Java objects exposed via javascript in the -ScriptCraft plugin … +ScriptCraft plugin: * `__plugin` – the ScriptCraft Plugin itself. This is a useful starting point for accessing other SpigotMC objects. The `__plugin` object is of type [org.bukkit.plugin.Plugin][api] and all - of its properties and methods are accessible. For example … `js + of its properties and methods are accessible. For example: `js __plugin.name` returns the plugin's name (JavaScript is more concise than the equivalent Java code: `__plugin.getName()` ). @@ -192,7 +197,7 @@ If you would like to contribute source code and/or documentation changes please ScriptCraft works with Bukkit Plugin and uses the Bukkit Configuration API. On first loading, ScriptCraft will create a config.yml file in -the plugins/scriptcraft/ directory. This file looks like this … +the plugins/scriptcraft/ directory. This file looks like this: extract-js: plugins: true @@ -229,7 +234,7 @@ programs and how to do the same thing in JavaScript. I highly recommend the series of [tutorials provided by CoderDojo Athenry][cda]. -Developer Chris Cacciatore has created some interesting tools using ScriptCraft … +Developer Chris Cacciatore has created some interesting tools using ScriptCraft: * [A wolf-bot][wb] * [L-Systems (Large-scale fractal structures in Minecraft)][ls] diff --git a/docs/API-Reference.md b/docs/API-Reference.md index b26f6d3..30875ce 100644 --- a/docs/API-Reference.md +++ b/docs/API-Reference.md @@ -52,18 +52,137 @@ Walter Higgins * [events.on() static method](#eventson-static-method) * [Events Helper Module (CanaryMod version)](#events-helper-module-canarymod-version) * [Usage](#usage) + * [events.minecartActivate()](#eventsminecartactivate) + * [events.villagerTradeUnlock()](#eventsvillagertradeunlock) + * [events.mobTarget()](#eventsmobtarget) + * [events.chickenLayEgg()](#eventschickenlayegg) + * [events.potionEffectFinish()](#eventspotioneffectfinish) + * [events.entityMove()](#eventsentitymove) + * [events.hangingEntityDestroy()](#eventshangingentitydestroy) + * [events.vehicleCollision()](#eventsvehiclecollision) + * [events.potionEffectApplied()](#eventspotioneffectapplied) + * [events.vehicleDestroy()](#eventsvehicledestroy) + * [events.vehicleEnter()](#eventsvehicleenter) + * [events.damage()](#eventsdamage) + * [events.entityMount()](#eventsentitymount) + * [events.slimeSplit()](#eventsslimesplit) + * [events.endermanDropBlock()](#eventsendermandropblock) + * [events.itemTouchGround()](#eventsitemtouchground) + * [events.entitySpawn()](#eventsentityspawn) + * [events.endermanPickupBlock()](#eventsendermanpickupblock) + * [events.vehicleDamage()](#eventsvehicledamage) + * [events.entityLightningStruck()](#eventsentitylightningstruck) + * [events.entityDespawn()](#eventsentitydespawn) + * [events.vehicleMove()](#eventsvehiclemove) + * [events.projectileHit()](#eventsprojectilehit) + * [events.entityDeath()](#eventsentitydeath) + * [events.entityTame()](#eventsentitytame) + * [events.vehicleExit()](#eventsvehicleexit) + * [events.dimensionSwitch()](#eventsdimensionswitch) + * [events.foodLevel()](#eventsfoodlevel) + * [events.bookEdit()](#eventsbookedit) + * [events.eat()](#eventseat) + * [events.playerList()](#eventsplayerlist) + * [events.playerIdle()](#eventsplayeridle) + * [events.enchant()](#eventsenchant) + * [events.playerArmSwing()](#eventsplayerarmswing) + * [events.teleport()](#eventsteleport) + * [events.anvilUse()](#eventsanviluse) + * [events.portalUse()](#eventsportaluse) + * [events.foodSaturation()](#eventsfoodsaturation) + * [events.connection()](#eventsconnection) + * [events.playerRespawned()](#eventsplayerrespawned) + * [events.armorBroken()](#eventsarmorbroken) + * [events.levelUp()](#eventslevelup) + * [events.blockRightClick()](#eventsblockrightclick) + * [events.itemDrop()](#eventsitemdrop) + * [events.itemFrameRotate()](#eventsitemframerotate) + * [events.playerRespawning()](#eventsplayerrespawning) + * [events.craft()](#eventscraft) + * [events.experience()](#eventsexperience) + * [events.signChange()](#eventssignchange) + * [events.healthChange()](#eventshealthchange) + * [events.disconnection()](#eventsdisconnection) + * [events.gameModeChange()](#eventsgamemodechange) + * [events.preConnection()](#eventspreconnection) + * [events.villagerTrade()](#eventsvillagertrade) + * [events.returnFromIdle()](#eventsreturnfromidle) + * [events.armorStandModify()](#eventsarmorstandmodify) + * [events.slotClick()](#eventsslotclick) + * [events.itemFrameSetItem()](#eventsitemframesetitem) + * [events.entityRightClick()](#eventsentityrightclick) + * [events.foodExhaustion()](#eventsfoodexhaustion) + * [events.chat()](#eventschat) + * [events.itemPickup()](#eventsitempickup) + * [events.bedExit()](#eventsbedexit) + * [events.blockPlace()](#eventsblockplace) + * [events.heldItemChange()](#eventshelditemchange) + * [events.toolBroken()](#eventstoolbroken) + * [events.kick()](#eventskick) + * [events.playerDeath()](#eventsplayerdeath) + * [events.blockLeftClick()](#eventsblockleftclick) + * [events.blockDestroy()](#eventsblockdestroy) + * [events.bedEnter()](#eventsbedenter) + * [events.signShow()](#eventssignshow) + * [events.inventory()](#eventsinventory) + * [events.playerMove()](#eventsplayermove) + * [events.itemUse()](#eventsitemuse) + * [events.ban()](#eventsban) + * [events.statGained()](#eventsstatgained) + * [events.smeltBegin()](#eventssmeltbegin) + * [events.treeGrow()](#eventstreegrow) + * [events.chunkCreated()](#eventschunkcreated) + * [events.liquidDestroy()](#eventsliquiddestroy) + * [events.chunkLoaded()](#eventschunkloaded) + * [events.pistonRetract()](#eventspistonretract) + * [events.smelt()](#eventssmelt) + * [events.blockUpdate()](#eventsblockupdate) + * [events.portalDestroy()](#eventsportaldestroy) + * [events.ignition()](#eventsignition) + * [events.redstoneChange()](#eventsredstonechange) + * [events.weatherChange()](#eventsweatherchange) + * [events.chunkCreation()](#eventschunkcreation) + * [events.hopperTransfer()](#eventshoppertransfer) + * [events.chunkUnload()](#eventschunkunload) + * [events.blockGrow()](#eventsblockgrow) + * [events.dispense()](#eventsdispense) + * [events.blockDropXp()](#eventsblockdropxp) + * [events.fireworkExplode()](#eventsfireworkexplode) + * [events.leafDecay()](#eventsleafdecay) + * [events.pistonExtend()](#eventspistonextend) + * [events.noteBlockPlay()](#eventsnoteblockplay) + * [events.lightningStrike()](#eventslightningstrike) + * [events.decorate()](#eventsdecorate) + * [events.explosion()](#eventsexplosion) + * [events.tNTActivate()](#eventstntactivate) + * [events.timeChange()](#eventstimechange) + * [events.flow()](#eventsflow) + * [events.portalCreate()](#eventsportalcreate) + * [events.blockPhysics()](#eventsblockphysics) + * [events.playerCommand()](#eventsplayercommand) + * [events.consoleCommand()](#eventsconsolecommand) + * [events.commandBlockCommand()](#eventscommandblockcommand) + * [events.loadWorld()](#eventsloadworld) + * [events.permissionCheck()](#eventspermissioncheck) + * [events.serverGuiStart()](#eventsserverguistart) + * [events.unloadWorld()](#eventsunloadworld) + * [events.pluginDisable()](#eventsplugindisable) + * [events.pluginEnable()](#eventspluginenable) + * [events.serverTick()](#eventsservertick) + * [events.serverListPing()](#eventsserverlistping) + * [events.serverShutdown()](#eventsservershutdown) * [Events Helper Module (SpigotMC version)](#events-helper-module-spigotmc-version) * [Usage](#usage-1) - * [events.weatherChange()](#eventsweatherchange) - * [events.lightningStrike()](#eventslightningstrike) + * [events.weatherChange()](#eventsweatherchange-1) + * [events.lightningStrike()](#eventslightningstrike-1) * [events.thunderChange()](#eventsthunderchange) - * [events.vehicleMove()](#eventsvehiclemove) - * [events.vehicleDestroy()](#eventsvehicledestroy) - * [events.vehicleExit()](#eventsvehicleexit) + * [events.vehicleMove()](#eventsvehiclemove-1) + * [events.vehicleDestroy()](#eventsvehicledestroy-1) + * [events.vehicleExit()](#eventsvehicleexit-1) * [events.vehicleEntityCollision()](#eventsvehicleentitycollision) * [events.vehicleBlockCollision()](#eventsvehicleblockcollision) - * [events.vehicleEnter()](#eventsvehicleenter) - * [events.vehicleDamage()](#eventsvehicledamage) + * [events.vehicleEnter()](#eventsvehicleenter-1) + * [events.vehicleDamage()](#eventsvehicledamage-1) * [events.vehicleUpdate()](#eventsvehicleupdate) * [events.vehicleCreate()](#eventsvehiclecreate) * [events.enchantItem()](#eventsenchantitem) @@ -86,7 +205,7 @@ Walter Higgins * [events.asyncPlayerChat()](#eventsasyncplayerchat) * [events.playerDropItem()](#eventsplayerdropitem) * [events.playerRegisterChannel()](#eventsplayerregisterchannel) - * [events.playerMove()](#eventsplayermove) + * [events.playerMove()](#eventsplayermove-1) * [events.playerItemBreak()](#eventsplayeritembreak) * [events.playerBucketEmpty()](#eventsplayerbucketempty) * [events.playerStatisticIncrement()](#eventsplayerstatisticincrement) @@ -130,33 +249,33 @@ Walter Higgins * [events.inventoryClick()](#eventsinventoryclick) * [events.inventoryClose()](#eventsinventoryclose) * [events.inventoryCreative()](#eventsinventorycreative) - * [events.inventory()](#eventsinventory) + * [events.inventory()](#eventsinventory-1) * [events.prepareItemCraft()](#eventsprepareitemcraft) * [events.furnaceExtract()](#eventsfurnaceextract) * [events.brew()](#eventsbrew) * [events.serverCommand()](#eventsservercommand) - * [events.serverListPing()](#eventsserverlistping) + * [events.serverListPing()](#eventsserverlistping-1) * [events.serviceRegister()](#eventsserviceregister) - * [events.pluginDisable()](#eventsplugindisable) + * [events.pluginDisable()](#eventsplugindisable-1) * [events.remoteServerCommand()](#eventsremoteservercommand) * [events.mapInitialize()](#eventsmapinitialize) * [events.tabComplete()](#eventstabcomplete) * [events.serviceUnregister()](#eventsserviceunregister) - * [events.pluginEnable()](#eventspluginenable) + * [events.pluginEnable()](#eventspluginenable-1) * [events.villagerAcquireTrade()](#eventsvillageracquiretrade) * [events.entityBreed()](#eventsentitybreed) * [events.entityAirChange()](#eventsentityairchange) - * [events.playerDeath()](#eventsplayerdeath) + * [events.playerDeath()](#eventsplayerdeath-1) * [events.enderDragonChangePhase()](#eventsenderdragonchangephase) * [events.entityCreatePortal()](#eventsentitycreateportal) * [events.entityCombust()](#eventsentitycombust) * [events.sheepDyeWool()](#eventssheepdyewool) * [events.expBottle()](#eventsexpbottle) - * [events.entityTame()](#eventsentitytame) + * [events.entityTame()](#eventsentitytame-1) * [events.projectileLaunch()](#eventsprojectilelaunch) * [events.entityDamage()](#eventsentitydamage) * [events.itemSpawn()](#eventsitemspawn) - * [events.projectileHit()](#eventsprojectilehit) + * [events.projectileHit()](#eventsprojectilehit-1) * [events.foodLevelChange()](#eventsfoodlevelchange) * [events.itemDespawn()](#eventsitemdespawn) * [events.villagerReplenishTrade()](#eventsvillagerreplenishtrade) @@ -164,8 +283,8 @@ Walter Higgins * [events.areaEffectCloudApply()](#eventsareaeffectcloudapply) * [events.entityPortal()](#eventsentityportal) * [events.entityTarget()](#eventsentitytarget) - * [events.entityDeath()](#eventsentitydeath) - * [events.entitySpawn()](#eventsentityspawn) + * [events.entityDeath()](#eventsentitydeath-1) + * [events.entitySpawn()](#eventsentityspawn-1) * [events.lingeringPotionSplash()](#eventslingeringpotionsplash) * [events.sheepRegrowWool()](#eventssheepregrowwool) * [events.entityShootBow()](#eventsentityshootbow) @@ -187,9 +306,9 @@ Walter Higgins * [events.playerLeashEntity()](#eventsplayerleashentity) * [events.spawnerSpawn()](#eventsspawnerspawn) * [events.itemMerge()](#eventsitemmerge) - * [events.slimeSplit()](#eventsslimesplit) + * [events.slimeSplit()](#eventsslimesplit-1) * [events.pigZap()](#eventspigzap) - * [events.fireworkExplode()](#eventsfireworkexplode) + * [events.fireworkExplode()](#eventsfireworkexplode-1) * [events.potionSplash()](#eventspotionsplash) * [events.entityChangeBlock()](#eventsentitychangeblock) * [events.entityPortalExit()](#eventsentityportalexit) @@ -201,8 +320,8 @@ Walter Higgins * [events.notePlay()](#eventsnoteplay) * [events.cauldronLevelChange()](#eventscauldronlevelchange) * [events.blockFade()](#eventsblockfade) - * [events.blockPlace()](#eventsblockplace) - * [events.blockPhysics()](#eventsblockphysics) + * [events.blockPlace()](#eventsblockplace-1) + * [events.blockPhysics()](#eventsblockphysics-1) * [events.blockIgnite()](#eventsblockignite) * [events.blockBreak()](#eventsblockbreak) * [events.blockBurn()](#eventsblockburn) @@ -210,10 +329,10 @@ Walter Higgins * [events.blockRedstone()](#eventsblockredstone) * [events.blockPistonRetract()](#eventsblockpistonretract) * [events.blockDispense()](#eventsblockdispense) - * [events.signChange()](#eventssignchange) + * [events.signChange()](#eventssignchange-1) * [events.blockPistonExtend()](#eventsblockpistonextend) * [events.blockCanBuild()](#eventsblockcanbuild) - * [events.blockGrow()](#eventsblockgrow) + * [events.blockGrow()](#eventsblockgrow-1) * [events.leavesDecay()](#eventsleavesdecay) * [events.blockExp()](#eventsblockexp) * [events.blockForm()](#eventsblockform) @@ -227,9 +346,9 @@ Walter Higgins * [events.worldInit()](#eventsworldinit) * [events.worldUnload()](#eventsworldunload) * [events.worldSave()](#eventsworldsave) - * [events.chunkUnload()](#eventschunkunload) + * [events.chunkUnload()](#eventschunkunload-1) * [events.chunkPopulate()](#eventschunkpopulate) - * [events.portalCreate()](#eventsportalcreate) + * [events.portalCreate()](#eventsportalcreate-1) * [events.chunkLoad()](#eventschunkload) * [console global variable](#console-global-variable) * [Example](#example) @@ -972,6 +1091,958 @@ to choose from any of the approx. 160 different event types to listen to. The crucial difference is that the events module now has functions for each of the built-in events. The functions are accessible via TAB-completion so will help beginning programmers to explore the events at the server console window. +### events.minecartActivate() + +#### Parameters + + * callback - A function which is called whenever the [entity.MinecartActivateHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/MinecartActivateHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.villagerTradeUnlock() + +#### Parameters + + * callback - A function which is called whenever the [entity.VillagerTradeUnlockHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/VillagerTradeUnlockHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.mobTarget() + +#### Parameters + + * callback - A function which is called whenever the [entity.MobTargetHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/MobTargetHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.chickenLayEgg() + +#### Parameters + + * callback - A function which is called whenever the [entity.ChickenLayEggHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/ChickenLayEggHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.potionEffectFinish() + +#### Parameters + + * callback - A function which is called whenever the [entity.PotionEffectFinishHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/PotionEffectFinishHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.entityMove() + +#### Parameters + + * callback - A function which is called whenever the [entity.EntityMoveHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/EntityMoveHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.hangingEntityDestroy() + +#### Parameters + + * callback - A function which is called whenever the [entity.HangingEntityDestroyHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/HangingEntityDestroyHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.vehicleCollision() + +#### Parameters + + * callback - A function which is called whenever the [entity.VehicleCollisionHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/VehicleCollisionHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.potionEffectApplied() + +#### Parameters + + * callback - A function which is called whenever the [entity.PotionEffectAppliedHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/PotionEffectAppliedHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.vehicleDestroy() + +#### Parameters + + * callback - A function which is called whenever the [entity.VehicleDestroyHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/VehicleDestroyHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.vehicleEnter() + +#### Parameters + + * callback - A function which is called whenever the [entity.VehicleEnterHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/VehicleEnterHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.damage() + +#### Parameters + + * callback - A function which is called whenever the [entity.DamageHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/DamageHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.entityMount() + +#### Parameters + + * callback - A function which is called whenever the [entity.EntityMountHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/EntityMountHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.slimeSplit() + +#### Parameters + + * callback - A function which is called whenever the [entity.SlimeSplitHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/SlimeSplitHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.endermanDropBlock() + +#### Parameters + + * callback - A function which is called whenever the [entity.EndermanDropBlockHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/EndermanDropBlockHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.itemTouchGround() + +#### Parameters + + * callback - A function which is called whenever the [entity.ItemTouchGroundHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/ItemTouchGroundHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.entitySpawn() + +#### Parameters + + * callback - A function which is called whenever the [entity.EntitySpawnHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/EntitySpawnHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.endermanPickupBlock() + +#### Parameters + + * callback - A function which is called whenever the [entity.EndermanPickupBlockHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/EndermanPickupBlockHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.vehicleDamage() + +#### Parameters + + * callback - A function which is called whenever the [entity.VehicleDamageHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/VehicleDamageHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.entityLightningStruck() + +#### Parameters + + * callback - A function which is called whenever the [entity.EntityLightningStruckHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/EntityLightningStruckHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.entityDespawn() + +#### Parameters + + * callback - A function which is called whenever the [entity.EntityDespawnHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/EntityDespawnHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.vehicleMove() + +#### Parameters + + * callback - A function which is called whenever the [entity.VehicleMoveHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/VehicleMoveHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.projectileHit() + +#### Parameters + + * callback - A function which is called whenever the [entity.ProjectileHitHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/ProjectileHitHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.entityDeath() + +#### Parameters + + * callback - A function which is called whenever the [entity.EntityDeathHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/EntityDeathHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.entityTame() + +#### Parameters + + * callback - A function which is called whenever the [entity.EntityTameHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/EntityTameHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.vehicleExit() + +#### Parameters + + * callback - A function which is called whenever the [entity.VehicleExitHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/VehicleExitHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.dimensionSwitch() + +#### Parameters + + * callback - A function which is called whenever the [entity.DimensionSwitchHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/entity/DimensionSwitchHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.foodLevel() + +#### Parameters + + * callback - A function which is called whenever the [player.FoodLevelHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/FoodLevelHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.bookEdit() + +#### Parameters + + * callback - A function which is called whenever the [player.BookEditHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/BookEditHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.eat() + +#### Parameters + + * callback - A function which is called whenever the [player.EatHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/EatHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.playerList() + +#### Parameters + + * callback - A function which is called whenever the [player.PlayerListHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/PlayerListHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.playerIdle() + +#### Parameters + + * callback - A function which is called whenever the [player.PlayerIdleHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/PlayerIdleHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.enchant() + +#### Parameters + + * callback - A function which is called whenever the [player.EnchantHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/EnchantHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.playerArmSwing() + +#### Parameters + + * callback - A function which is called whenever the [player.PlayerArmSwingHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/PlayerArmSwingHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.teleport() + +#### Parameters + + * callback - A function which is called whenever the [player.TeleportHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/TeleportHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.anvilUse() + +#### Parameters + + * callback - A function which is called whenever the [player.AnvilUseHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/AnvilUseHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.portalUse() + +#### Parameters + + * callback - A function which is called whenever the [player.PortalUseHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/PortalUseHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.foodSaturation() + +#### Parameters + + * callback - A function which is called whenever the [player.FoodSaturationHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/FoodSaturationHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.connection() + +#### Parameters + + * callback - A function which is called whenever the [player.ConnectionHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ConnectionHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.playerRespawned() + +#### Parameters + + * callback - A function which is called whenever the [player.PlayerRespawnedHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/PlayerRespawnedHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.armorBroken() + +#### Parameters + + * callback - A function which is called whenever the [player.ArmorBrokenHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ArmorBrokenHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.levelUp() + +#### Parameters + + * callback - A function which is called whenever the [player.LevelUpHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/LevelUpHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.blockRightClick() + +#### Parameters + + * callback - A function which is called whenever the [player.BlockRightClickHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/BlockRightClickHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.itemDrop() + +#### Parameters + + * callback - A function which is called whenever the [player.ItemDropHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ItemDropHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.itemFrameRotate() + +#### Parameters + + * callback - A function which is called whenever the [player.ItemFrameRotateHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ItemFrameRotateHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.playerRespawning() + +#### Parameters + + * callback - A function which is called whenever the [player.PlayerRespawningHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/PlayerRespawningHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.craft() + +#### Parameters + + * callback - A function which is called whenever the [player.CraftHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/CraftHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.experience() + +#### Parameters + + * callback - A function which is called whenever the [player.ExperienceHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ExperienceHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.signChange() + +#### Parameters + + * callback - A function which is called whenever the [player.SignChangeHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/SignChangeHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.healthChange() + +#### Parameters + + * callback - A function which is called whenever the [player.HealthChangeHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/HealthChangeHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.disconnection() + +#### Parameters + + * callback - A function which is called whenever the [player.DisconnectionHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/DisconnectionHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.gameModeChange() + +#### Parameters + + * callback - A function which is called whenever the [player.GameModeChangeHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/GameModeChangeHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.preConnection() + +#### Parameters + + * callback - A function which is called whenever the [player.PreConnectionHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/PreConnectionHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.villagerTrade() + +#### Parameters + + * callback - A function which is called whenever the [player.VillagerTradeHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/VillagerTradeHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.returnFromIdle() + +#### Parameters + + * callback - A function which is called whenever the [player.ReturnFromIdleHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ReturnFromIdleHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.armorStandModify() + +#### Parameters + + * callback - A function which is called whenever the [player.ArmorStandModifyHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ArmorStandModifyHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.slotClick() + +#### Parameters + + * callback - A function which is called whenever the [player.SlotClickHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/SlotClickHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.itemFrameSetItem() + +#### Parameters + + * callback - A function which is called whenever the [player.ItemFrameSetItemHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ItemFrameSetItemHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.entityRightClick() + +#### Parameters + + * callback - A function which is called whenever the [player.EntityRightClickHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/EntityRightClickHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.foodExhaustion() + +#### Parameters + + * callback - A function which is called whenever the [player.FoodExhaustionHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/FoodExhaustionHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.chat() + +#### Parameters + + * callback - A function which is called whenever the [player.ChatHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ChatHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.itemPickup() + +#### Parameters + + * callback - A function which is called whenever the [player.ItemPickupHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ItemPickupHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.bedExit() + +#### Parameters + + * callback - A function which is called whenever the [player.BedExitHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/BedExitHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.blockPlace() + +#### Parameters + + * callback - A function which is called whenever the [player.BlockPlaceHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/BlockPlaceHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.heldItemChange() + +#### Parameters + + * callback - A function which is called whenever the [player.HeldItemChangeHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/HeldItemChangeHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.toolBroken() + +#### Parameters + + * callback - A function which is called whenever the [player.ToolBrokenHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ToolBrokenHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.kick() + +#### Parameters + + * callback - A function which is called whenever the [player.KickHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/KickHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.playerDeath() + +#### Parameters + + * callback - A function which is called whenever the [player.PlayerDeathHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/PlayerDeathHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.blockLeftClick() + +#### Parameters + + * callback - A function which is called whenever the [player.BlockLeftClickHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/BlockLeftClickHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.blockDestroy() + +#### Parameters + + * callback - A function which is called whenever the [player.BlockDestroyHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/BlockDestroyHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.bedEnter() + +#### Parameters + + * callback - A function which is called whenever the [player.BedEnterHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/BedEnterHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.signShow() + +#### Parameters + + * callback - A function which is called whenever the [player.SignShowHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/SignShowHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.inventory() + +#### Parameters + + * callback - A function which is called whenever the [player.InventoryHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/InventoryHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.playerMove() + +#### Parameters + + * callback - A function which is called whenever the [player.PlayerMoveHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/PlayerMoveHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.itemUse() + +#### Parameters + + * callback - A function which is called whenever the [player.ItemUseHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/ItemUseHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.ban() + +#### Parameters + + * callback - A function which is called whenever the [player.BanHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/BanHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.statGained() + +#### Parameters + + * callback - A function which is called whenever the [player.StatGainedHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/player/StatGainedHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.smeltBegin() + +#### Parameters + + * callback - A function which is called whenever the [world.SmeltBeginHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/SmeltBeginHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.treeGrow() + +#### Parameters + + * callback - A function which is called whenever the [world.TreeGrowHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/TreeGrowHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.chunkCreated() + +#### Parameters + + * callback - A function which is called whenever the [world.ChunkCreatedHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/ChunkCreatedHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.liquidDestroy() + +#### Parameters + + * callback - A function which is called whenever the [world.LiquidDestroyHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/LiquidDestroyHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.chunkLoaded() + +#### Parameters + + * callback - A function which is called whenever the [world.ChunkLoadedHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/ChunkLoadedHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.pistonRetract() + +#### Parameters + + * callback - A function which is called whenever the [world.PistonRetractHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/PistonRetractHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.smelt() + +#### Parameters + + * callback - A function which is called whenever the [world.SmeltHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/SmeltHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.blockUpdate() + +#### Parameters + + * callback - A function which is called whenever the [world.BlockUpdateHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/BlockUpdateHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.portalDestroy() + +#### Parameters + + * callback - A function which is called whenever the [world.PortalDestroyHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/PortalDestroyHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.ignition() + +#### Parameters + + * callback - A function which is called whenever the [world.IgnitionHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/IgnitionHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.redstoneChange() + +#### Parameters + + * callback - A function which is called whenever the [world.RedstoneChangeHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/RedstoneChangeHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.weatherChange() + +#### Parameters + + * callback - A function which is called whenever the [world.WeatherChangeHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/WeatherChangeHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.chunkCreation() + +#### Parameters + + * callback - A function which is called whenever the [world.ChunkCreationHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/ChunkCreationHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.hopperTransfer() + +#### Parameters + + * callback - A function which is called whenever the [world.HopperTransferHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/HopperTransferHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.chunkUnload() + +#### Parameters + + * callback - A function which is called whenever the [world.ChunkUnloadHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/ChunkUnloadHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.blockGrow() + +#### Parameters + + * callback - A function which is called whenever the [world.BlockGrowHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/BlockGrowHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.dispense() + +#### Parameters + + * callback - A function which is called whenever the [world.DispenseHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/DispenseHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.blockDropXp() + +#### Parameters + + * callback - A function which is called whenever the [world.BlockDropXpHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/BlockDropXpHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.fireworkExplode() + +#### Parameters + + * callback - A function which is called whenever the [world.FireworkExplodeHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/FireworkExplodeHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.leafDecay() + +#### Parameters + + * callback - A function which is called whenever the [world.LeafDecayHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/LeafDecayHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.pistonExtend() + +#### Parameters + + * callback - A function which is called whenever the [world.PistonExtendHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/PistonExtendHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.noteBlockPlay() + +#### Parameters + + * callback - A function which is called whenever the [world.NoteBlockPlayHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/NoteBlockPlayHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.lightningStrike() + +#### Parameters + + * callback - A function which is called whenever the [world.LightningStrikeHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/LightningStrikeHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.decorate() + +#### Parameters + + * callback - A function which is called whenever the [world.DecorateHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/DecorateHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.explosion() + +#### Parameters + + * callback - A function which is called whenever the [world.ExplosionHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/ExplosionHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.tNTActivate() + +#### Parameters + + * callback - A function which is called whenever the [world.TNTActivateHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/TNTActivateHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.timeChange() + +#### Parameters + + * callback - A function which is called whenever the [world.TimeChangeHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/TimeChangeHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.flow() + +#### Parameters + + * callback - A function which is called whenever the [world.FlowHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/FlowHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.portalCreate() + +#### Parameters + + * callback - A function which is called whenever the [world.PortalCreateHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/PortalCreateHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.blockPhysics() + +#### Parameters + + * callback - A function which is called whenever the [world.BlockPhysicsHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/world/BlockPhysicsHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.playerCommand() + +#### Parameters + + * callback - A function which is called whenever the [command.PlayerCommandHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/command/PlayerCommandHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.consoleCommand() + +#### Parameters + + * callback - A function which is called whenever the [command.ConsoleCommandHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/command/ConsoleCommandHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.commandBlockCommand() + +#### Parameters + + * callback - A function which is called whenever the [command.CommandBlockCommandHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/command/CommandBlockCommandHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.loadWorld() + +#### Parameters + + * callback - A function which is called whenever the [system.LoadWorldHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/system/LoadWorldHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.permissionCheck() + +#### Parameters + + * callback - A function which is called whenever the [system.PermissionCheckHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/system/PermissionCheckHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.serverGuiStart() + +#### Parameters + + * callback - A function which is called whenever the [system.ServerGuiStartHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/system/ServerGuiStartHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.unloadWorld() + +#### Parameters + + * callback - A function which is called whenever the [system.UnloadWorldHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/system/UnloadWorldHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.pluginDisable() + +#### Parameters + + * callback - A function which is called whenever the [system.PluginDisableHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/system/PluginDisableHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.pluginEnable() + +#### Parameters + + * callback - A function which is called whenever the [system.PluginEnableHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/system/PluginEnableHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.serverTick() + +#### Parameters + + * callback - A function which is called whenever the [system.ServerTickHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/system/ServerTickHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.serverListPing() + +#### Parameters + + * callback - A function which is called whenever the [system.ServerListPingHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/system/ServerListPingHook.html) is fired + + * priority - optional - see events.on() for more information. + +### events.serverShutdown() + +#### Parameters + + * callback - A function which is called whenever the [system.ServerShutdownHook event](https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/system/ServerShutdownHook.html) is fired + + * priority - optional - see events.on() for more information. + ## Events Helper Module (SpigotMC version) The Events helper module provides a suite of functions - one for each possible event. For example, the events.blockBreak() function is just a wrapper function which calls events.on(org.bukkit.event.block.BlockBreakEvent, callback, priority) diff --git a/docs/YoungPersonsGuideToProgrammingMinecraft.md b/docs/YoungPersonsGuideToProgrammingMinecraft.md index c2016cf..a41d973 100644 --- a/docs/YoungPersonsGuideToProgrammingMinecraft.md +++ b/docs/YoungPersonsGuideToProgrammingMinecraft.md @@ -7,8 +7,8 @@ If you would like to make changes, change file src/docs/templates/ypgpm.md inste # The Young Person's Guide to Programming in Minecraft ## Table of Contents * [Introduction](#introduction) - * [Installation](#installation) - * [CanaryMod and Permissions](#canarymod-and-permissions) + * [Installing and Running SpigotMC](#installing-and-running-spigotmc) + * [Installing ScriptCraft](#installing-scriptcraft) * [Configuring your Server (optional)](#configuring-your-server-optional) * [Learning Javascript](#learning-javascript) * [First Steps](#first-steps) @@ -43,7 +43,6 @@ If you would like to make changes, change file src/docs/templates/ypgpm.md inste * [Keeping Score - Lookup tables in Javascript](#keeping-score---lookup-tables-in-javascript) * [Counting block break events for each player](#counting-block-break-events-for-each-player) * [Next Steps](#next-steps) - ## Introduction Minecraft is an open-ended 3D game where you can build and craft @@ -63,82 +62,40 @@ players connect to a Minecraft Server on the internet or locally ![Cottages created using ScriptCraft in MineCraft][img_cr] -## Installation +# Installation -CanaryMod is a version of the Minecraft server software which allows -easy addition of 'Mods' and extensions to Minecraft. ScriptCraft is a -'Mod' for use with CanaryMod. Adding Mods to Minecraft can be -difficult but CanaryMod makes it easy. Follow these steps to -Install ScriptCraft on your computer... +Before installing ScriptCraft you must first install SpigotMC which is +a special version of Minecraft Server that makes it easy to customize +the game. -1. [Download and install CanaryMod][dlcm] then follow the [CanaryMod - Installation Instructions][cmadmin]. +## Installing and Running SpigotMC -2. Start the CanaryMod server, then once it has started up, stop it - by typing 'stop'. If you go to the CanaryMod folder (see step 1) you - should see some new files and subfolders. +Follow these steps to download and install SpigotMC. -3. [Download the latest version of the ScriptCraft Mod][sc-plugin]. Then copy the ScriptCraft.jar file to the - `plugins` folder (This folder won't be created until you run CanaryMod for the first time (see previous step). +1. Download Spigot's [BuildTools.jar][spigotdl] +2. Save the BuildTools.jar file to a new directory called spigotmc. +3. Open a terminal (Mac and Linux) or command prompt (windows) window and type `java -jar BuildTools.jar`. This will kick off a long series of commands to "build" SpigotMC. +4. When the build is done, there will be a new file beginning with `spigot` and ending in `.jar` in the spigotmc directory. Run this file by typing `java -jar spigot-1.10.2.jar` (it might not be that exact name - you can list files in the directory by typing `dir` (Windows) or `ls` (Mac and Linux). +5. The server will start up then shut down very shortly afterwards. You'll need to edit a file called `eula.txt` - change `eula=false` to `eula=true` and save the file. +6. Run the `java -jar spigot-1.10.2.jar` command again - this time the server will start up. Shut it down by typing `stop` at the server prompt. -4. Start up the CanaryMod server again (see [instructions for starting the server][cmadmin]). +## Installing ScriptCraft -5. In the CanaryMod command window type `op {your_username}` and hit - enter, replacing {your_username} with your own minecraft - username. This will give you `operator` access meaning you can perform - more commands than are normally available in Minecraft. You should - make yourself a server operator (Server operators have full privileges - for the server) permanently by editing the ops.txt file - and adding your username (one username per line). +Follow these steps to download and install ScriptCraft. -6. In the CanaryMod command window type `js 1 + 1` and hit enter. You should see `> 2` . +1. Download the [scriptcraft.jar][dl] plugin and save it to the `plugins` directory and restart the server by typing `java -jar spigot-1.10.2.jar`. +2. At the server prompt type `js 1 + 1` and hit enter. The result `2` should be displayed. -... Congratulations! You just installed your own Minecraft Server with -the ScriptCraft Mod and are now ready to begin programming in Minecraft. - -Normally, Minecraft Mods are written in Java. This makes writing your -own extension or game rules difficult because you must first learn Java. -Java is different enough from Javascript. With the ScriptCraft plug-in -installed, you don't have to learn Java, you can extend and customize -Minecraft your way using Javascript. Javascript is easier to learn than -Java but it's also more flexible and powerful and is used for creating -interactive web sites and many other applications. - -## CanaryMod and Permissions -CanaryMod works slightly differently to CraftBukkit in how it handles -permissions and groups. By default, there are 4 groups: visitors, -players, mods and admins. Each player who joins the game is added to the -'visitors' group. This group has no permissions by default so -visitors can't break or place blocks. If you would like to change this -behaviour then issue the following command at the console window: - - groupmod permission add visitors canary.world.build - -If you would like all admins to have scripting ability then issue the -following command: - - groupmod permission add admins scriptcraft.evaluate - -This will enable all admins on your server to issue javascript statements. -All operators can issue any command (including the `/js` command to evaluate javascript). -For more information on CanaryMod's Permissions and Groups see the following: - - * [Permissions and Groups][cmPerms] - * [List of Permissions][cmPermsList] - -[cmPerms]: https://github.com/walterhiggins/canarymod-admin-guide#permissions-and-groups-1 -[cmPermsList]: https://github.com/walterhiggins/canarymod-admin-guide#list-of-permissions-1 +Congratulations - you've just installed your Custom Minecraft Server and are ready to begin writing your first mod! ## Configuring your Server (optional) -Once you've installed CanaryMod, depending on your specific needs, -you might want to consider setting the following properties in the `server.cfg` or `config/worlds//.cfg` files ... +Once you've installed SpigotMC, depending on your specific needs, +you might want to consider setting the following properties in the `server.properties` file: # completely flat worlds are best for building from scratch # bukkit/spigotmc level-type=FLAT - # canarymod - world-type=FLAT generate-structures=false # creative mode @@ -673,19 +630,17 @@ compare the ages of your friends or siblings to your own age. You can find out if you can Fly in minecraft by typing the following statement ... - /js self.getCapabilities().mayFly() + /js self.allowFlight ... the result will be `true` or `false` depending on whether you can fly or not. You can turn on and off your ability to fly by setting -your `mayFly` property to `true` or `false`. Try it ... +your `allowFlight` property to `true` or `false`. Try it ... - /js self.capabilities.flying = true - /js self.updateCapabilities() + /js self.allowFlight = true; ... Now you can fly! Double-press the space bar key to start flying. To turn off flight ... - /js self.capabilities.flying = false; - /js self.updateCapabilities() + /js self.allowFlight = false; ... and you come crashing down to earth. This is just one example of how `true` and `false` are used throughout ScriptCraft – these are @@ -694,55 +649,56 @@ Maths Professor at University College Cork. There are plenty more examples of boolean values in Minecraft. You can find out if it's raining in your minecraft world by typing the following statement ... - /js self.world.raining + /js self.world.hasStorm() ... The result of this statement will be either `false` (if it's not raining) or `true` (if it *is* raining). If it's raining, you can make it stop raining typing the following command: - /js self.world.raining = false + /js self.world.setStorm(false) ... Similarly, to make it start raining you can issue the following command: - /js self.world.raining = true + /js self.world.setStorm( true ) ### Booleans and JavaBeans There are many *boolean* properties you can use to turn on or off -certain game behaviours. For example, the *raining* behavior is turned -on or off using the World's `raining` property. The World object's -properties and methods are [documented on the CanaryMod JavaDocs World -page][cmworld]. When browsing the CanaryMod JavaDoc pages, whenever -you see a method whose name begins with `is` such as `isRaining()` and -a companion method `setRaining()`, these methods are called *JavaBean* -methods - the *raining* property is a *JavaBean* property and there +certain game behaviours. For example, the *thundering* behavior is turned +on or off using the World's `thundering` property. The World object's +properties and methods are [documented on the SpigotMC JavaDocs World +page][spworld]. When browsing the SpigotMC JavaDoc pages, whenever +you see a method whose name begins with `is` such as `isThundering()` and +a companion method `setThundering()`, these methods are called *JavaBean* +methods - the *thundering* property is a *JavaBean* property and there are two ways you can use JavaBean properties in Javascript. You can *get* and *set* the property using the methods provided by Java. To -*get* the raining property you can call the JavaBean Method: +*get* the thundering property you can call the JavaBean Method: - /js self.world.isRaining() + /js self.world.isThundering() ... or you can get the property like this: - /js self.world.raining + /js self.world.thundering -To *set* the raining property, you can call the JavaBean method: +To *set* the thundering property, you can call the JavaBean method: - /js self.world.setRaining( true ) + /js self.world.setThundering( true ) ... or you can set the property like this: - /js self.world.raining = true + /js self.world.thundering = true Whatever approach you use, the result will be the same. [cmworld]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/api/world/World.html +[spworld]: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/World.html ### SIDENOTE You may be wondering how to change other aspects of the Minecraft game - pretty much all aspects of the game can be changed. Changes are made using what are called `API` calls - these are calls to functions and methods in -Minecraft - you can read more about these on the [CanaryMod API -Reference][cmapi]. +Minecraft - you can read more about these on the [SpigotMC API +Reference][spigotapi]. ## ...and Again, and Again, and Again,... @@ -943,8 +899,10 @@ var utils = require('utils'); var players = utils.players(); var sounds = require('sounds'); utils.foreach( players, function( player ) { - sounds.catMeow( player ); // canarymod sounds.entityCatAmbient( player ); // spigot 1.9 + /* canarymod only + sounds.catMeow( player ); + */ } ); ``` @@ -1066,7 +1024,7 @@ This time no message should appear on your screen. The `if` statement tests to see if something is `true` or `false` and if `true` then the block of code between the curly braces ( `{` and `}` ) is executed - but only if the condition is true. The condition -in the above example is `!self.onGround` (self is not on ground) which +in the above example is `!self.onGround` (self is _not_ on ground) which will be `true` if you are currently flying or `false` if you aren't. What if you wanted to display a message only if a condition is *not* @@ -1122,29 +1080,29 @@ following code sends a message to any player who breaks a block in the game... ```javascript -function myBlockDestroyHook( event ){ +function myBlockBreakHook( event ){ var breaker = event.player; echo( breaker, 'You broke a block'); } -events.blockDestroy( myBlockDestroyHook ); +events.blockBreak( myBlockBreakHook ); ``` -The `events.blockDestroy()` function is just one of the many `events` functions which can be used to *register* a function to be called whenever a particular type of event occurs. In the -above code the blockDestroy function takes as a parameter a function +The `events.blockBreak()` function is just one of the many `events` functions which can be used to *register* a function to be called whenever a particular type of event occurs. In the +above code the blockBreak function takes as a parameter a function I want to be called when that event occurs. The function I want called in turn takes 1 parameter. The `event` object has all the information about the event which just occurred. I can tell who broke the block and send a message to the player. The important thing to note is that -the `myBlockDestroyHook` function defined above will not be called until a player breaks a +the `myBlockBreakHook` function defined above will not be called until a player breaks a block. Try it - save the above code in a new file in the `scriptcraft/plugins` directory then type `/js refresh()` to reload scriptcraft. Then break a block in the game and you should see the message 'You broke a block'. There are many types of events you can listen for in Minecraft. You can -browse [all possible event registration functions][cmevts2] in the API Reference. +browse [all possible event registration functions][spevts2] in the API Reference. -For custom events (events which aren't in the net.canarymod.hook tree) +For custom events (events which aren't in the org.bukkit.event tree) just specify the fully qualified class name instead. E.g. ... events.on ( net.yourdomain.events.YourEvent, function( event ) { @@ -1156,12 +1114,12 @@ just specify the fully qualified class name instead. E.g. ... If you want an event handler to only execute once, you can remove the handler like this... ```javascript -function myBlockDestroyHook( evt ) { +function myBlockBreakHook( evt ) { var breaker = evt.player; echo( breaker, 'You broke a block'); this.unregister(); } -events.blockDestroy( myBlockDestroyHook ); +events.blockBreak( myBlockBreakHook ); ``` The `this.unregister();` statement will remove this function from the @@ -1173,11 +1131,11 @@ to stop listening for events. To unregister a listener *outside* of the listener function... ```javascript -function myBlockDestroyHook( evt ){ +function myBlockBreakHook( evt ){ var breaker = evt.player; echo( breaker, 'You broke a block'); } -var myBlockBreakListener = events.blockDestroy( myBlockDestroyHook ); +var myBlockBreakListener = events.blockBreak( myBlockBreakHook ); ... myBlockBreakListener.unregister(); ``` @@ -1297,7 +1255,7 @@ var breaks = {}; function initializeBreakCount( event ){ breaks[event.player.name] = 0; } -events.connection( initializeBreakCount ); +events.playerJoin( initializeBreakCount ); /* every time a player breaks a block increase their block-break-count @@ -1307,7 +1265,7 @@ function incrementBreakCount( event ){ var breakCount = breaks[event.player.name]; echo( event.player, 'You broke ' + breakCount + ' blocks'); } -events.blockDestroy( incrementBreakCount ); +events.blockBreak( incrementBreakCount ); ``` With a little more work, you could turn this into a game where players @@ -1325,8 +1283,8 @@ minecraft, I recommend reading the accompanying [ScriptCraft API reference][api] which covers all of the ScriptCraft functions, objects and methods. I also recommend reading the source code to some of the existing scriptcraft plugins, followed by -[Anatomy of a ScriptCraft Plug-in][ap]. The online [CanaryMod API -Reference][cmapi] provides lots of valuable information about the +[Anatomy of a ScriptCraft Plug-in][ap]. The online [SpigotMC API +Reference][spigotapi] provides lots of valuable information about the different objects and methods available for use by ScriptCraft. @@ -1340,6 +1298,7 @@ different objects and methods available for use by ScriptCraft. [np]: http://notepad-plus-plus.org/ [cbapi]: http://jd.bukkit.org/beta/apidocs/ [cmapi]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/ +[spigotapi]: https://hub.spigotmc.org/javadocs/spigot/ [boole]: http://en.wikipedia.org/wiki/George_Boole [soundapi]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/api/world/effects/SoundEffect.Type.html [ap]: Anatomy-of-a-Plugin.md @@ -1348,6 +1307,7 @@ different objects and methods available for use by ScriptCraft. [bkevts]: http://jd.bukkit.org/dev/apidocs/org/bukkit/event/package-summary.html [cmevts]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/package-summary.html [cmevts2]: API-Reference.md#events-helper-module-canary-version +[spevts2]: API-Reference.md#events-helper-module-spigotmc-version [img_echo_date]: img/ypgpm_echo_date.png [img_3d_shapes]: img/ypgpm_3dshapes.jpg [img_whd]: img/ypgpm_whd.jpg diff --git a/src/docs/js/generateEventsHelper.js b/src/docs/js/generateEventsHelper.js index 5d5a203..d32fcb8 100644 --- a/src/docs/js/generateEventsHelper.js +++ b/src/docs/js/generateEventsHelper.js @@ -3,6 +3,7 @@ args = Array.prototype.slice.call(args,1); var File = java.io.File, FileReader = java.io.FileReader, FileInputStream = java.io.FileInputStream, + FRAMEWORK = args[0], out = java.lang.System.out, err = java.lang.System.err, Modifier = java.lang.reflect.Modifier, @@ -12,7 +13,7 @@ var File = java.io.File, entry = null; var content = [ '/*********************', - '## Events Helper Module (' + args[0] + ' version)', + '## Events Helper Module (' + FRAMEWORK + ' version)', 'The Events helper module provides a suite of functions - one for each possible event.', 'For example, the events.' + args[2] + '() function is just a wrapper function which calls events.on(' + args[3] + ', callback, priority)', 'This module is a convenience wrapper for easily adding new event handling functions in Javascript. ', @@ -30,7 +31,7 @@ var content = [ '***/' ]; var canary = false; -if (args[0] == 'canary'){ +if (FRAMEWORK == 'CanaryMod'){ canary = true; } @@ -89,10 +90,9 @@ while ( ( entry = zis.nextEntry) != null) { out.println(comment[i]); } out.println('exports.' + fname + ' = function(callback,priority){ '); - if (args[0] == 'canary'){ + if (canary){ out.println(' return events.on(Packages.' + name + ',callback,priority);'); - } - if (args[0] == 'bukkit'){ + } else { out.println(' return events.on(' + name + ',callback,priority);'); } out.println('};'); diff --git a/src/docs/templates/ypgpm.md b/src/docs/templates/ypgpm.md index 5c29cda..445166c 100644 --- a/src/docs/templates/ypgpm.md +++ b/src/docs/templates/ypgpm.md @@ -1,4 +1,3 @@ - ## Introduction Minecraft is an open-ended 3D game where you can build and craft @@ -18,82 +17,40 @@ players connect to a Minecraft Server on the internet or locally ![Cottages created using ScriptCraft in MineCraft][img_cr] -## Installation +# Installation -CanaryMod is a version of the Minecraft server software which allows -easy addition of 'Mods' and extensions to Minecraft. ScriptCraft is a -'Mod' for use with CanaryMod. Adding Mods to Minecraft can be -difficult but CanaryMod makes it easy. Follow these steps to -Install ScriptCraft on your computer... +Before installing ScriptCraft you must first install SpigotMC which is +a special version of Minecraft Server that makes it easy to customize +the game. -1. [Download and install CanaryMod][dlcm] then follow the [CanaryMod - Installation Instructions][cmadmin]. +## Installing and Running SpigotMC -2. Start the CanaryMod server, then once it has started up, stop it - by typing 'stop'. If you go to the CanaryMod folder (see step 1) you - should see some new files and subfolders. +Follow these steps to download and install SpigotMC. -3. [Download the latest version of the ScriptCraft Mod][sc-plugin]. Then copy the ScriptCraft.jar file to the - `plugins` folder (This folder won't be created until you run CanaryMod for the first time (see previous step). +1. Download Spigot's [BuildTools.jar][spigotdl] +2. Save the BuildTools.jar file to a new directory called spigotmc. +3. Open a terminal (Mac and Linux) or command prompt (windows) window and type `java -jar BuildTools.jar`. This will kick off a long series of commands to "build" SpigotMC. +4. When the build is done, there will be a new file beginning with `spigot` and ending in `.jar` in the spigotmc directory. Run this file by typing `java -jar spigot-1.10.2.jar` (it might not be that exact name - you can list files in the directory by typing `dir` (Windows) or `ls` (Mac and Linux). +5. The server will start up then shut down very shortly afterwards. You'll need to edit a file called `eula.txt` - change `eula=false` to `eula=true` and save the file. +6. Run the `java -jar spigot-1.10.2.jar` command again - this time the server will start up. Shut it down by typing `stop` at the server prompt. -4. Start up the CanaryMod server again (see [instructions for starting the server][cmadmin]). +## Installing ScriptCraft -5. In the CanaryMod command window type `op {your_username}` and hit - enter, replacing {your_username} with your own minecraft - username. This will give you `operator` access meaning you can perform - more commands than are normally available in Minecraft. You should - make yourself a server operator (Server operators have full privileges - for the server) permanently by editing the ops.txt file - and adding your username (one username per line). +Follow these steps to download and install ScriptCraft. -6. In the CanaryMod command window type `js 1 + 1` and hit enter. You should see `> 2` . +1. Download the [scriptcraft.jar][dl] plugin and save it to the `plugins` directory and restart the server by typing `java -jar spigot-1.10.2.jar`. +2. At the server prompt type `js 1 + 1` and hit enter. The result `2` should be displayed. -... Congratulations! You just installed your own Minecraft Server with -the ScriptCraft Mod and are now ready to begin programming in Minecraft. - -Normally, Minecraft Mods are written in Java. This makes writing your -own extension or game rules difficult because you must first learn Java. -Java is different enough from Javascript. With the ScriptCraft plug-in -installed, you don't have to learn Java, you can extend and customize -Minecraft your way using Javascript. Javascript is easier to learn than -Java but it's also more flexible and powerful and is used for creating -interactive web sites and many other applications. - -## CanaryMod and Permissions -CanaryMod works slightly differently to CraftBukkit in how it handles -permissions and groups. By default, there are 4 groups: visitors, -players, mods and admins. Each player who joins the game is added to the -'visitors' group. This group has no permissions by default so -visitors can't break or place blocks. If you would like to change this -behaviour then issue the following command at the console window: - - groupmod permission add visitors canary.world.build - -If you would like all admins to have scripting ability then issue the -following command: - - groupmod permission add admins scriptcraft.evaluate - -This will enable all admins on your server to issue javascript statements. -All operators can issue any command (including the `/js` command to evaluate javascript). -For more information on CanaryMod's Permissions and Groups see the following: - - * [Permissions and Groups][cmPerms] - * [List of Permissions][cmPermsList] - -[cmPerms]: https://github.com/walterhiggins/canarymod-admin-guide#permissions-and-groups-1 -[cmPermsList]: https://github.com/walterhiggins/canarymod-admin-guide#list-of-permissions-1 +Congratulations - you've just installed your Custom Minecraft Server and are ready to begin writing your first mod! ## Configuring your Server (optional) -Once you've installed CanaryMod, depending on your specific needs, -you might want to consider setting the following properties in the `server.cfg` or `config/worlds//.cfg` files ... +Once you've installed SpigotMC, depending on your specific needs, +you might want to consider setting the following properties in the `server.properties` file: # completely flat worlds are best for building from scratch # bukkit/spigotmc level-type=FLAT - # canarymod - world-type=FLAT generate-structures=false # creative mode @@ -628,19 +585,17 @@ compare the ages of your friends or siblings to your own age. You can find out if you can Fly in minecraft by typing the following statement ... - /js self.getCapabilities().mayFly() + /js self.allowFlight ... the result will be `true` or `false` depending on whether you can fly or not. You can turn on and off your ability to fly by setting -your `mayFly` property to `true` or `false`. Try it ... +your `allowFlight` property to `true` or `false`. Try it ... - /js self.capabilities.flying = true - /js self.updateCapabilities() + /js self.allowFlight = true; ... Now you can fly! Double-press the space bar key to start flying. To turn off flight ... - /js self.capabilities.flying = false; - /js self.updateCapabilities() + /js self.allowFlight = false; ... and you come crashing down to earth. This is just one example of how `true` and `false` are used throughout ScriptCraft – these are @@ -649,55 +604,56 @@ Maths Professor at University College Cork. There are plenty more examples of boolean values in Minecraft. You can find out if it's raining in your minecraft world by typing the following statement ... - /js self.world.raining + /js self.world.hasStorm() ... The result of this statement will be either `false` (if it's not raining) or `true` (if it *is* raining). If it's raining, you can make it stop raining typing the following command: - /js self.world.raining = false + /js self.world.setStorm(false) ... Similarly, to make it start raining you can issue the following command: - /js self.world.raining = true + /js self.world.setStorm( true ) ### Booleans and JavaBeans There are many *boolean* properties you can use to turn on or off -certain game behaviours. For example, the *raining* behavior is turned -on or off using the World's `raining` property. The World object's -properties and methods are [documented on the CanaryMod JavaDocs World -page][cmworld]. When browsing the CanaryMod JavaDoc pages, whenever -you see a method whose name begins with `is` such as `isRaining()` and -a companion method `setRaining()`, these methods are called *JavaBean* -methods - the *raining* property is a *JavaBean* property and there +certain game behaviours. For example, the *thundering* behavior is turned +on or off using the World's `thundering` property. The World object's +properties and methods are [documented on the SpigotMC JavaDocs World +page][spworld]. When browsing the SpigotMC JavaDoc pages, whenever +you see a method whose name begins with `is` such as `isThundering()` and +a companion method `setThundering()`, these methods are called *JavaBean* +methods - the *thundering* property is a *JavaBean* property and there are two ways you can use JavaBean properties in Javascript. You can *get* and *set* the property using the methods provided by Java. To -*get* the raining property you can call the JavaBean Method: +*get* the thundering property you can call the JavaBean Method: - /js self.world.isRaining() + /js self.world.isThundering() ... or you can get the property like this: - /js self.world.raining + /js self.world.thundering -To *set* the raining property, you can call the JavaBean method: +To *set* the thundering property, you can call the JavaBean method: - /js self.world.setRaining( true ) + /js self.world.setThundering( true ) ... or you can set the property like this: - /js self.world.raining = true + /js self.world.thundering = true Whatever approach you use, the result will be the same. [cmworld]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/api/world/World.html +[spworld]: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/World.html ### SIDENOTE You may be wondering how to change other aspects of the Minecraft game - pretty much all aspects of the game can be changed. Changes are made using what are called `API` calls - these are calls to functions and methods in -Minecraft - you can read more about these on the [CanaryMod API -Reference][cmapi]. +Minecraft - you can read more about these on the [SpigotMC API +Reference][spigotapi]. ## ...and Again, and Again, and Again,... @@ -898,8 +854,10 @@ var utils = require('utils'); var players = utils.players(); var sounds = require('sounds'); utils.foreach( players, function( player ) { - sounds.catMeow( player ); // canarymod sounds.entityCatAmbient( player ); // spigot 1.9 + /* canarymod only + sounds.catMeow( player ); + */ } ); ``` @@ -1021,7 +979,7 @@ This time no message should appear on your screen. The `if` statement tests to see if something is `true` or `false` and if `true` then the block of code between the curly braces ( `{` and `}` ) is executed - but only if the condition is true. The condition -in the above example is `!self.onGround` (self is not on ground) which +in the above example is `!self.onGround` (self is _not_ on ground) which will be `true` if you are currently flying or `false` if you aren't. What if you wanted to display a message only if a condition is *not* @@ -1077,29 +1035,29 @@ following code sends a message to any player who breaks a block in the game... ```javascript -function myBlockDestroyHook( event ){ +function myBlockBreakHook( event ){ var breaker = event.player; echo( breaker, 'You broke a block'); } -events.blockDestroy( myBlockDestroyHook ); +events.blockBreak( myBlockBreakHook ); ``` -The `events.blockDestroy()` function is just one of the many `events` functions which can be used to *register* a function to be called whenever a particular type of event occurs. In the -above code the blockDestroy function takes as a parameter a function +The `events.blockBreak()` function is just one of the many `events` functions which can be used to *register* a function to be called whenever a particular type of event occurs. In the +above code the blockBreak function takes as a parameter a function I want to be called when that event occurs. The function I want called in turn takes 1 parameter. The `event` object has all the information about the event which just occurred. I can tell who broke the block and send a message to the player. The important thing to note is that -the `myBlockDestroyHook` function defined above will not be called until a player breaks a +the `myBlockBreakHook` function defined above will not be called until a player breaks a block. Try it - save the above code in a new file in the `scriptcraft/plugins` directory then type `/js refresh()` to reload scriptcraft. Then break a block in the game and you should see the message 'You broke a block'. There are many types of events you can listen for in Minecraft. You can -browse [all possible event registration functions][cmevts2] in the API Reference. +browse [all possible event registration functions][spevts2] in the API Reference. -For custom events (events which aren't in the net.canarymod.hook tree) +For custom events (events which aren't in the org.bukkit.event tree) just specify the fully qualified class name instead. E.g. ... events.on ( net.yourdomain.events.YourEvent, function( event ) { @@ -1111,12 +1069,12 @@ just specify the fully qualified class name instead. E.g. ... If you want an event handler to only execute once, you can remove the handler like this... ```javascript -function myBlockDestroyHook( evt ) { +function myBlockBreakHook( evt ) { var breaker = evt.player; echo( breaker, 'You broke a block'); this.unregister(); } -events.blockDestroy( myBlockDestroyHook ); +events.blockBreak( myBlockBreakHook ); ``` The `this.unregister();` statement will remove this function from the @@ -1128,11 +1086,11 @@ to stop listening for events. To unregister a listener *outside* of the listener function... ```javascript -function myBlockDestroyHook( evt ){ +function myBlockBreakHook( evt ){ var breaker = evt.player; echo( breaker, 'You broke a block'); } -var myBlockBreakListener = events.blockDestroy( myBlockDestroyHook ); +var myBlockBreakListener = events.blockBreak( myBlockBreakHook ); ... myBlockBreakListener.unregister(); ``` @@ -1252,7 +1210,7 @@ var breaks = {}; function initializeBreakCount( event ){ breaks[event.player.name] = 0; } -events.connection( initializeBreakCount ); +events.playerJoin( initializeBreakCount ); /* every time a player breaks a block increase their block-break-count @@ -1262,7 +1220,7 @@ function incrementBreakCount( event ){ var breakCount = breaks[event.player.name]; echo( event.player, 'You broke ' + breakCount + ' blocks'); } -events.blockDestroy( incrementBreakCount ); +events.blockBreak( incrementBreakCount ); ``` With a little more work, you could turn this into a game where players @@ -1280,8 +1238,8 @@ minecraft, I recommend reading the accompanying [ScriptCraft API reference][api] which covers all of the ScriptCraft functions, objects and methods. I also recommend reading the source code to some of the existing scriptcraft plugins, followed by -[Anatomy of a ScriptCraft Plug-in][ap]. The online [CanaryMod API -Reference][cmapi] provides lots of valuable information about the +[Anatomy of a ScriptCraft Plug-in][ap]. The online [SpigotMC API +Reference][spigotapi] provides lots of valuable information about the different objects and methods available for use by ScriptCraft. @@ -1295,6 +1253,7 @@ different objects and methods available for use by ScriptCraft. [np]: http://notepad-plus-plus.org/ [cbapi]: http://jd.bukkit.org/beta/apidocs/ [cmapi]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/ +[spigotapi]: https://hub.spigotmc.org/javadocs/spigot/ [boole]: http://en.wikipedia.org/wiki/George_Boole [soundapi]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/api/world/effects/SoundEffect.Type.html [ap]: Anatomy-of-a-Plugin.md @@ -1303,6 +1262,7 @@ different objects and methods available for use by ScriptCraft. [bkevts]: http://jd.bukkit.org/dev/apidocs/org/bukkit/event/package-summary.html [cmevts]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/package-summary.html [cmevts2]: API-Reference.md#events-helper-module-canary-version +[spevts2]: API-Reference.md#events-helper-module-spigotmc-version [img_echo_date]: img/ypgpm_echo_date.png [img_3d_shapes]: img/ypgpm_3dshapes.jpg [img_whd]: img/ypgpm_whd.jpg