Documentation

Now, you are probably thinking 'why the world am I documenting everything?'. Well, I can tell you from personal experience, it pays off. I have gone back time and again to correct an error, or enhance a script only to spend 2 hours trying to understand my own structure. If you still don't think documentation is important, go ahead and skip this section, you'll only be setting yourself up for a fall later.

With documentation, there are two types:

• Commented Documentation
• Implanted Documentation.

To draw a single line, use a # sign right before the comment.
To write a comment block, use =begin and =end.

For example:

=begin
This is a comment block.  It will appear green, and doesn't do anything to the code.
=end

#pops up the the first actor in the database.  This is a comment line.
print $game_actors[1]

The second type of documentation is 'implanted'. This means the names that you give variables, classes, etc. will describe what it does. For example, we can assume the variable @str refers to strength simply because 'STR' is the abbreviation for strength. It is important to give your variables meaningful names that are easy to remember. Last thing you want is something like this:

@leon = @bung + @hole

Variable Types

Now, onto variable types. There are 5 different variable types, and this section will tell you each and give a very brief description of each:

• local_variable
  • A variable usable only inside a method. I'll explain methods later.
• @instance_variable
  • A variable usable throughout instance methods of a entire class. Each instance of a class has a copy of this variable and it is not shared among instances of a class.
• @@class_variable]
  • A variable usable throughout the entire class. This type of variable is shared among instances of a class. You must initialize this to a value before it is used.
• $global_variable
  • A variable usable anywhere in the program.
• Constant_Variable
  • A variable exclusive to a class/module that never changes. (Though, Ruby defeats the purpose, enabling you to change the constant during run-time.)

The structure of a script - Classes and Methods

All right, now we are going to take a look at the structure of a script. By now, you are probably thinking 'Let's get on with the scripting already!'. Well, if you are thinking that, I have a word of advice: You cannot build a house if you don't know how to frame it. All that means is if you don't know the structure, you can't expect it to work very well.

Classes
For classes, there is one thing we must answer before we even start writing the class, and that is what it will be used for. The reason: We need to know if there is a superclass. A superclass a class that this class will gain abilities from, if that makes sense. For example:

If you were going to make a window, you would choose from the following list of superclasses: Window_Base, Window_Selectable, and Window_Command. Each one of these has their own superclass, and it all traces back to the emperor! Wait, wrong movie. It all traces back to the class 'Window'. In fact, here is a look at how it all works:

Window -> Window_Base -> Window_Selectable -> Window_Command

• Window_Base has all of the abilities of Window.
• Window_Selectable has all of the abilities of Window and Window_Base.
• Window_Command has the abilities of all three.

That is an explanation of a superclass. It is a class that is a 'parent class' to another class. So Window_Base has the superclass of Window.

Why is this important? Well, it is either that, or you can write out the code for each and every window separately... making each one about 200 lines rather than about.... 20. Now that we know what a superclass is, let's look at the structure of a class:

class Class_Example
  def method_one
  end 
  def method_two
  end
end

Methods
Well, inside we have 'def method_one'. def is the keyword for defining a method. Everything inside of the method will trigger whenever the method is called, and it will be triggered in order.

After this, we have end. end is needed every time you use something like class or method. There are many other things you will need to use end for, so you will see it alot. Basically, it ends the current process.

Now, as a quick review: A class is a collection of methods that all work together to serve a purpose. A method is a code snippet that triggers when called.

Now you know what a class is, what a superclass is, what a method is, and what end does. You also know the variable types. In the next section, we'll cover:

• How to use all of these together to make a simple window.
• Showing the power of superclasses.
• Show how to call methods.

How a class works

First, we'll cover a class that is NOT a scene. Scenes work a little differently because of the script 'Main'. But, we'll start with a basic class. Scenes will wait until lesson 2, because they require a few different techniques.

A class has simple requirements: A unique name, the initialize method, the end of initialize, and the end of the class. Everything else isn't required at all, granted, without anything else it is useless. The structure is very simple (and always remember to indent!)

class Class_Name #This is the same as a constant variable.
  def initialize #The initialize method, it is always called.  If not there, we have a problem...
  end #To end initialize
end #To end the class

class Class_Name #This is the same as a constant variable.
  def initialize #The initialize method, it is always called.  If not there, we have a problem...
    print "Lizzie"
  end #To end initialize
end #To end the class

Almost everything in scripting deals with variables taht are defined in other locations, but we'll start you off with variables from the same method, then same class, then work on variables from outside the class. To define a variable, you write the variables name For example, an instance variable could be: @variable.

To give a variable meaning, we use the equal sign. So to give @variable meaning, we'd do something like this:
@variable = 0
Now, @variable equals 0. So whenever we call it, it will always be '0'. And, if we put @variable = 0 above print "Lizzie", then changed "Lizzie" to @variable, it would pop up the number 0. So, the code would look like:

class Class_Name #This is the same as a constant variable.
  def initialize #The initialize method, it is always called.  If not there, we have a problem...
    @variable = 0  #defines @variable
    print @variable  #Prints @variable.
  end #To end initialize
end #To end the class

class Class_Name
  def initialize
    @variable = 0
    method_2  #Calls method_2
  end
  
  def method_2  #method_2
    print @variable
  end
end

Now, you should know how a class structure works. You start with the class name, then the method (you have to use def to define it, don't forget!), then insert anything in the method, close it, add another if needed, close it if another exists, then close the class.

Now, with all of this out of the way, you should know the following:

• What a class is and how to create it.
• What a method is and how to create one.
• What each variable type is and how to define a variable.

Assignment

All right, so we went over the structure of a class, over a method, etc etc etc... now, it is assignment time. I will ask you just to write a snippet of code and do some vocabulary. Not too hard, eh? Now, here we go: (And please, try this without notes before you attempt this.)

Vocabulary:

• method
• class
• $global_variable
• print
• @@class_variable
• Constant_Variable

The assignment
Make a working class that is called in a 'Call Script' (from the event editor in RPG Maker XP) named 'Class_Test' (Don't forget the 'new'!)

In the class, there needs to be two methods: initialize and one of any name you wish.

In the initialization, define 1 local variable and 2 instance variables, and print hte local variable.

In the second method, print the other two instance variables.