Adventurecraft Scripting (JavaScript)

Intro Edit

This guide is written to help two groups of users. Readers with no previous scripting or coding experience should start at the very Basics. Readers with previous scripting or coding experience, start at AdventureCraft Scripting Features and use Classes and Objects for a reference.

The Very Basics Edit

So you're new to programming. Let me be the first to welcome you! Once you realize how a programmer's brain works, you'll be better in JavaScript and AC's script blocks!

Logical Thinking Edit

Normally, when people think of a thing that might happen, they say: "I'm going to say hello when the door opens." Although this is grammatically correct, a programmer is more likely say: "If the door opens, I'm going to say hello." This is because of how the syntax, or sentence structure, for most programming and scripting languages work.

Scripting Syntax Edit

Hello World! Yes, this example has been overused... but it's a good start, so why not! Many languages don't simply output whatever you type. For example: a JavaScript file containing just the words "Hello world" will blow up in your face. To make JavaScript do something, you must put it in a 'function' or 'method'. The function for showing a message is pretty straight forward.

chat.print("Hello world!");

Let's split this into 3 parts: chat., print(); and "Hello world!"

The chat. part is the 'object' we're going to use, in this case we want to display a message in the chat window, so we use the 'chat' object. The print() part is the 'function', functions are parts of the script that actually do something. Most of the functions are either part of JavaScript, or created by Cryect. However, you can define your own functions, but that will come at a later part in the tutorial. The "Hello world!" is a 'parameter' of the function, parameters are the input of a function, so the structure of this line would be:

object.function(parameter1);

Conditional Statements Edit

Very often when you write code, you want to perform different actions for different decisions. You can use conditional statements in your code to do this. In JavaScript we have the following conditional statements:

if - use this statement to execute some code only if a specified condition is true

if...else - use this statement to execute some code if the condition is true and another code if the condition is false

if...else if....else - use this statement to select one of many blocks of code to be executed switch use this statement to select one of many blocks of code to be executed

if

Here, we will go back to the logical thinking bit. Now, let's say you want to show a message when the player dies. You would probably say, "Say 'Game Over!' when the player dies." But a programmer would say, "If player is not alive, say 'Game Over!'"

if (!player.isAlive())
{
chat.print("Game Over!");
}

Let's split this up as well. if() {}, !, player., isAlive(), and chat.print("Game Over!");

The if() {} part is the if statement. Inside the parentheses is your condition, and inside the brackets is what it will do if the conditions are true. The ! is the not symbol. If the player is not alive. The player. part is the object. It represents the player. The isAlive() is the function. It says 'true' if the object running it is alive. "If the player is not alive," becomes "If not true." The chat.print("Game Over!"); is the parameter. The parameters run when the condition is true. The structure of an if statement is:

if (condition)
{
parameter1;
parameter2;
parameter3;
etc;
}

if...else

Now, let's say you still want to show a message when the player dies, however you also want something done if the player is still alive.

if (!player.isAlive())
{
chat.print("Game Over!");
} else {
// Player is still alive
}

if...else if...else

This builds on what is learned in the previous

if (var == 0)
{
chat.print("var = 0!");
} else if (var == 1) {
chat.print("var = 1!");
} else {
chat.print("var = ?!");
}

switch

Alternative to if...else if...else

switch(var)
{
case 0:
chat.print("var = 0!");
break;
case 1:
chat.print("var = 1!");
break;
default:
// Lands here, if you don't land in any of the above named cases
chat.print("var = ?!");
// No break needed in the last case
}

AdventureCraft Scripting Features Edit

Scripts for AdventureCraft must be in the .js (JavaScript) format and must be in the "scripts" folder:
AdventureCraft Folder/maps/Your Map/scripts
Simple variables persist between saves in AdventureCraft (includes strings, booleans, and number variables). You can assign three scripts globally using the /config command. These are:

  1. OnNewSave, which runs once and only when a new save is created from the map.
  2. OnLoad, which runs once each time the save is loaded.
  3. OnUpdate, which runs every tick, or twentieth a second, when the save is loaded.

Where textures are used, the filename is from the main map folder, as in "/mob/example.png" Where sounds are used, the filename to play a sound like "/sound/my sound.ogg" would be "sound.my sound". Customizable Mob Spawners have a special variable, spawnedEntities, that is an array of the entities they spawn. Script Blocks have their coordinates loaded into xCoord, yCoord, and zCoord. Scripts named item_##.js will be executed when the player tries to use an item with the ID ##. For subtypes, it's item_aa_bb.js, where 'aa' is the item ID and 'bb' is the damage value. The lastItemUsed variable will contain the item that was last used. Make note that when a scripted item is used and is in the offhand, it is swapped into the main hand for an instant. The hitEntity variable will contain the creature that was last hit. The hitBlock variable will contain the block that was last hit. Scripts named itemonAddToSlot##.js will be executed when an item with the ID ## is added to a previously empty slot and itemonRemovedFromSlot##.js when an item stack is removed from a slot. Subtypes work the same way as before. the slotID variable will contain the respective slot.

Music Scripts Edit

Using the musicScripts.txt file in your map's folder, you can assign scripts to certain patterns of notes. An example would be: 555, driveMad.js, Song of Madness Notes can be played using 0-9 on the keyboard. So, the above example would run the script called driveMad.js when the player plays 5 three times. Sharps are played using shift+number. 2, 6, and 9 do not have sharps. To represent sharps in scripts, use shift+number. If you want the player to play 4-sharp 5 7 4-sharp 5 7, you'd use the following: $57$57, driveMad.js, Song of Madness

Some helpful stuff:

Notepad ++ Autocomplete Plugin Edit

Here is a little Notepad ++ Plugin, Icecream Einoir made for Autocompleting AdventureCraft functions and classes. How to install: Download the "javascript.xml" file from the link below and replace the file with the "javascript.xml" in "NOTEPAD INSTALLATION DESTINATION\Notepad++\autoCompletion"

Download Plugin here

AdventureCraft Data Values Edit

Here are the Data Values of AdventureCraft: Additionally you can use this script to get the ids within your map:
Data Values Plugin (made by Rafreak800)

Entities View Follows Player

If you make an own Mob (Entity) and want them to face the player, this calculation will help you out:
Follow Player View Script

WIP