Introduction

Prerequisites

• Completion of parts 1 and 2 of this tutorial
  
• A ready mind, ready to learn and not skip over parts missing important details
  

Funny Skit

The BBSO walks in and congratulates you, "Very good job on your first plugin, it works beautifully, but what's all this talk about functions, constructors, variables, and classes?"

"Well," you reply, "that's what I'm learning about next. Let's do this part together."

The BBSO leans over, slipping over the banana peel you had forgotten to throw in the trash yesterday during your mad coding session.

Defining the Terms

Variables

A variable holds a value or a reference to a class in your code. They are created like this:

type name = value;

Example:

int speed = 30;

There are two different types of variables, those referencing primitive types: int, boolean, char, among others, and those referencing entire classes. You've already used a variable in your first program. In this case it was the sender variable that got passed to the function onCommand().

Below is a reference for all the primitive data types in java and what they do:

• int - This is referred to as an integer and can hold whole numbers from -2,147,483,648 to 2,147,483,647 (inclusive). This is usually what you will be using when you are storing numbers. If you try storing a number bigger or small than it can hold it will wrap around like a car speedometer.
  
• byte - This is the smallest form of the integer and can only hold numbers from -128 to 127. Bytes are used quite often in Minecraft code for storing block IDs to damage values. Of course Minecraft can store block IDs bigger than 127 but, we'll cover how that's possible just a bit later.
  
• short - This is in between the size of the byte and integer and can hold numbers from -32,768 to 32,767.
  
• long - For those times when an integer just isn't big enough you can use a long which can hold numbers from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, which should be big enough for just about any situation, unless you're trying to figure out the size of the universe in millimeters.
  
• double - If you've been wondering how you are going to save the number 2.54 in your program, this is the data type for you as it can store decimal numbers. The scope of how big or small of a number it can hold is beyond the objective of this tutorial though.
  
• float - when you are trying to save space this is equivalent to a short in the decimal world. If you are wanting to learn more about the exact values a float and double can store consult the official java documentation.
  
• boolean - Ah, a boolean, it can only store 1 and 0, or what we usually use in programming, true and false. We usually use it when we are expecting a yes/no response or a success/failure in programming.
  
• char - You can use this data type to store a single unicode character, like this: char colorcode = 'u00A7'; Most of the time you will be wanting to store an entire sentence or phrase, which you will want to use the String class for.
  
• String - although this isn't a primitive type, it's a simple data type and can be declared almost exactly like a primitive type. We use it quite a bit in programming plugins to hold text. To make a String you just do: String thetext = "This is the sample text";
  

Declaring variable references to classes is done similarly:

ClassName instancename = new ClassName();

Functions

Ah, beautiful functions. They can be as simple as just setting/getting a variable for you (we call those setters and getters), or as complex as separating a list of players into teams and returning them alphabetically. So, how exactly is a function built? Well, I'm glad you asked. A function is made using this format:

scope returnType name(VariableType variabletopass, VariableType variable2) { statements to execute }

Example:

public boolean isOnline(Player playername) {
boolean playeronline = playername.isOnline();
return playeronline;
}

Now, here comes the tricky part when it comes to passing variables. If you are passing primitive types, like int and boolean, you are only passing a copy of them. When you are passing Class instances you are passing the actual class itself, so any changes you do to the class will be reflected in the calling class.

Example:

public void changeThis(int number, ExampleClass theclass) {
//The int won't be affected in any way in the calling class
number = number + 5;
//The variable that we are setting here will be set in the calling class as well
theclass.setVariable(number);
}

Now you might have noticed that I didn't have a return statement in the previous example. That's because the function has a special return type: void, which means it doesn't return anything, so we don't need a statement to return anything. If we did want to terminate the function early we could use the return function by itself, without telling it a variable/value to return.

Hmm, okay, that's all fine and dandy, but there's one more thing you should know about functions: overloading them. No, that doesn't mean putting more data through them than they can accept, but re-declaring the function name, just with different variables, or more variables being passed to it. Below is an example of an overloaded function:

---

public void addPlayer(Player player) {
array.add(player.getName());
}

public void addPlayer(String player) {
array.add(player);
}

---

As you can see, both of the functions add the player, yet one accepts a string, and the other one accepts a player object (an object is an instance of a class). There's just one word of caution: You cannot overload a function with the same types just with different variable names as there is no way for Java to know which one you are wanting.

Classes

No, these aren't like classes in your school where you learn certain subjects, they're more like real world objects that encasulate a range of functions and do a useful part in your program. A class can be used to hold data about a player, or do complex and wonderful things, just like a chest in Minecraft can hold your items, or how a zombie has a complex path finding AI to find you.

Let's take a look at a car, and put it into class form. A car has many different things, it's got buttons, levers, switches, lights, and pedals. These are like the functions in a class. You push the gas pedal "gas(int amount)" and the car moves. You can look at the speedometer and figure out how fast you are moving "public int getSpeed()" among other things.

A class would hold all the information about that car, including make, model and all the stuff needed to make it work and interact with it's environment. Now, let's take that into actual class form.

A class is a container that holds variables and functions that all relate in some way so that you can refer to them in an orderly fashion and a way to keep them all together.Co

Constructors

So, what exactly is a constructor? A constructor is a special type of function that is used to set up a new instance of a class. A constructor for a class must be the same name as the class name, and does not have a return type. Here's an example class with a constructor:

ExampleClass.java

---

package tux2.example;


public class ExampleClass {

boolean issetup = false;

//The constructor
public ExampleClass() {
issetup = true;
}
}

---

Now, just like regular functions, constructors can also require you to pass certain variables, like the instance of your plugin, or other needed data, like the player name that is needed to set up the class for use. Also, just like functions, you can overload constructors as well.

Packages

I know we've already touched on packages, but I feel it should be touched on yet again in this section now that you have more of an understanding of how everything works. A package is a way of organizing your classes. Instead of having all of your classes in one package (the default package), you can file them away into separate folders, or packages. Making your plugin neater, as well as making sure your classes don't conflict with classes with the same name in other plugins. Classes in the same package as the class you are currently working on can be referred to directly, while classes that you need in other packages need an import statement at the top of your plugin letting your plugin know which class of that name you want to use. Just like we imported the JavaPlugin class in our first plugin.

Summary

Well, before I make your head explode, I think I should wrap up this lesson. Since the material in this lesson is quite complex and inter-related I highly suggest you read it at least twice in order to fully understand everything which is taught here.

In this lesson you learned about variables, functions, classes, and packages, as well as all of the primitive data types you can use for variables. In the next part we will be covering proper formatting of your plugin and formatting conventions.

<< Part 2 - Hello World!