[X] My Assistant

[Dubealex]

RGSS & Ruby Lesson - Chapter 1

BEFORE using any code from this tutorial, set your browser's character encoding to UTF-8, you will find this option in the VIEW menu.

Please, read this lessons fully, it took time to write and gather all the informations to do it. And I would not like to be asked a question about something I answered in a particular section of the lesson. As example: I am explaining the structure of a Object Oriented language in section 3, and RGSS/Ruby is Object Oriented, which means I won't necessarly write it again. (But I may just write a reference that informations can be found on Section 3.)

I may quote other website about Ruby and RGSS, and then explains what it means if it need details. When the text isn't inside quotation mark or inside a quote table, it means I wrote it.

In every step on the way, I may have "discarded" or "missed" some details about the true fundaments of some concept; this is because I am trying to explains RGSS, not complete programming. So I will stick to what is useful to know to be able to better comprehend how to code with RGSS, for RMXP Scripts.

Also note that the RGSS Reference I did is a good place to get raw syntaxes that RGSS uses to manipulate eveything, you can found that reference on my official website.

1- What Is Ruby ?

*From RubyCentral:

Ruby is a an exciting new, pure, object oriented programming language. While few people in the West have heard of Ruby yet, it has taken off like wildfire in Japan---already overtaking the Python language in popularity.

What makes Ruby so popular? Ruby weaves the best features of the best programming languages into a seamless, concise whole. Ruby is:

Powerful -- Ruby combines the pure object-oriented power of the classic OO language Smalltalk with the expressiveness and convenience of a scripting language such as Perl. Ruby programs are compact, yet very readable and maintainable; you can get a lot done in a few lines, without being cryptic.

Simple -- The syntax and semantics are intuitive and very clean. There aren't any "special cases" you have to remember. For instance, integers, classes, and nil are all objects, just like everything else. Once you learn the basics, it's easy to guess how to do new things---and guess correctly.

Transparent -- Ruby frees you from the drudgery of spoon-feeding the compiler. More than any other language we've worked with, Ruby stays out of your way, so you can concentrate on solving the problem at hand.

Available -- Ruby is open source and freely available for both development and deployment. Unlike some other new languages, Ruby does not restrict you to a single platform or vendor. You can run Ruby under Unix or Linux, Microsoft Windows, or specialized systems such as BeOS and others.
Most of all, Ruby puts the fun back into programming. When was the last time you had fun writing a program---a program that worked the first time; a program that you could read next week, next month, or next year and still understand exactly what it does? We find Ruby to be a breath of fresh air in the dense, often hectic world of programming. In fact, we see nothing but smiles after we present Ruby to programmers.

[...]

Ruby is a genuine object-oriented language. Everything you manipulate is an object, and the results of those manipulations are themselves objects

[...]

Like Perl, Ruby is good at text processing. Like Smalltalk, everything in Ruby is an object, and Ruby has blocks, iterators, meta-classes and other good stuff.

You can use Ruby to write servers, experiment with prototypes, and for everyday programming tasks. As a fully-integrated object-oriented language, Ruby scales well.

Ruby features:

Simple syntax,
Basic OO features (classes, methods, objects, and so on),
Special OO features (Mix-ins, singleton methods, renaming, ...),
Operator overloading,
Exception handling,
Iterators and closures,
Garbage collection,
Dynamic loading (depending on the architecture),
High transportability (runs on various Unices, Windows, DOS, OSX, OS/2, Amiga, and so on)

So, as you can see, Ruby is an Object Oriented Language; more details about what is an Object Oriented Language will follow. The fact that Ruby is open source allow you to freely download the tools to create Ruby programs from any website. CLICK HERE to see the available download on the official Ruby website.

2- History Of Ruby:

*From RubyCentral:

Ruby was created by Yukihiro Matsumoto (who goes by the handle "matz")

Influenced by Perl, Matz wanted to use a jewel name for his new language, so he named Ruby after a colleague's birthstone.

Later, he realized that Ruby comes right after Perl in several situations. In birthstones, pearl is June, ruby is July. When measuring font sizes, pearl is 5pt, ruby is 5.5pt. He thought Ruby was a good name for a programming language newer (and hopefully better) than Perl.

[...]

The following are quotes from Matz Post on Ruby Talk:

"Well, Ruby was born on February 24, 1993. I was talking with my colleague about the possibility of an object-oriented scripting language. I knew Perl (Perl4, not Perl5), but I didn't like it really, because it had smell of toy language (it still has). the object-oriented scripting language seemed very promising."

"I knew Python then. But I didn't like it, because I didn't think it was a true object-oriented language---OO features appeared to be add-on to the language. As a language manic and OO fan for 15 years, I really wanted a genuine object-oriented, easy-to-use scripting language. I looked for, but couldn't find one."

"So, I decided to make it. It took several months to make the interpreter run. I put it the features I love to have in my language, such as iterators, exception handling, garbage collection."

"Then, I reorganized the features of Perl into a class library, and implemented them. I posted Ruby 0.95 to the Japanese domestic newsgroups in Dec. 1995."

"Since then, highly active mailing lists have been established and web pages formed."

3- What Is "Object Oriented" or OO ?

An Object-Oriented language -- Known as OO -- is a language in which everything you manipulate is known as an "Object".

(Notes: A "language" is the collection of syntax, terms, rules and structure that is used to create a program. C++, Java and Ruby are all different "languages".)

Every OO languages have at least one similarity, which is that they are OO languages; the basic structure in which they operate is the same. An OO language concist of the following main components/functions:

-Class
-Methods
-Messages
-Arguments
-Variables/Constants

 rgss_lesson1.jpg ( 24.25k ) Number of downloads: 5697


Explanation of the diagram:
- A class contains variables and methods definitions.
- A method contains variables definitions and code.
- A message may contains arguments.
- An object is an instance of a class.
- An object communicate via Messages and Arguments.

Example of Object Instances:
Let's see a class as a car factory, and an object as the cars themselves. The car factory contains all the necessary "functions" to built a car, and each car is viewed as differents instance of the same thing. Those car "instances" are then different objects, and can be modified without affecting the other car objects. When the car company need another car, they can simply ask their factory to built a new one; once a factory (a class) is built, it saves time as you don't have to manually re-do each car (object).

Example of Communication & Object Properties:
When you want to access a properties of an object, you need to send a message to it, so it will be able to give you an answer -- And when you want to change an object properties, you need to send a message too, so it can be modified. In RPG Maker XP, an hero have many properties; such as "Name", "HP" and "Level". When you open the main menu in your game, you can see those properties (Level, Name and HP) on the screen. In the background, what RPG Maker XP did is to send a message to the Hero object asking for information about its properties.

A method actually defines what messages an object will be able to receive, and what will happen when it receives it. In this sense, an object is linked to it's creator (the class) as each time a message is send or sent from and to the object, the relevant method in that class is executed.

Back to our Hero example: This means that the class defining an Hero in RPG Maker XP has a method for every message you can send to its objects instances. Meaning that you will found a method called "name" in there; this method will define what will happen when that message is sent/received.

4- What Is RGSS ?

RGSS means "Ruby Game Scripting System". RGSS uses Ruby as it's language, so if you know Ruby, you also know RGSS. The difference between Ruby and RGSS that are important to you to know is that RGSS should be seen as a "Scripting" language that uses already maded components. In Ruby only, if you want to show a picture on screen, you cannot just use the same syntax you used in RPG Maker XP RGSS, you would have to code all that function from the ground up.

Example of RGSS code to show a picture (More infos on that later on.):

CODE

image = Sprite.new
image.bitmap = RPG::Cache.picture(name of picture)

So, basically, you need 2 lines to show a picture on screen; because you are using a class named "Sprite" already programmed inside RPG Maker XP (Not available in the Script Editor.) And you are also using a module "RPG" also not found in the Script Editor. This all makes your works easier and faster to code your game.

But since RGSS uses Ruby, and that RPG Maker XP uses Ruby (Version 1.8.1), you can code a full new "Sprite" class and use it, or even add functions in it.

So, all this means that RGSS is fairly less complicated than Ruby, because the low-level operation are handled by RPG maker XP, you don't have to code them.

(Note: low-level operation means the thing you would need to code to show a picture, talk to the machine (to Windows) to read a file, display a file, etc.)

5- RPG Maker XP Script Editor

RPG Maker XP comes with a Script Editor built-in to allow you to edit/add what we call "Scripts". Those scripts are actually RGSS code (Using the Ruby Syntax and power) that allow you to add or modify features in RPG Maker XP. When you open the Script Editor, you can see that many "Script" are already in there; those are the default scripts that make a default game run; as the Heros we talked earlier in section 3. The way Enterbrain classified the scripts is by "Class". Every class is in its own page (Although you can mix many class in the same page.)

To open the script editor, you can press F11, use the Tool Menu and choose "Script Editor" or use the toolbar icon.

 rgss_lesson3.jpg ( 99.45k ) Number of downloads: 3727


What I mean by "Real class name" is that the name you give to a page (The "Page Name" section, to the bottom left of the window) has nothing to do with the class name, it's just the name of the script. It can be anything, it doesn't have to be the class name, since as I said earlier, you can add many different class in the same page.

Color Code:

The following color code is used when editing your scripts, take note that this color convention is almost the same as for Ruby Programming. (Some color tag were discarded...)

Blue:
Blue represent the code syntax, as def, class, end, when, if, case, etc.
 rgss_lesson2.jpg ( 1.97k ) Number of downloads: 1785


Red:
Red represent numbers in your code. As 1, 2, 3 and 5.
 rgss_lesson4.jpg ( 1.59k ) Number of downloads: 174


Light Blue:
The lighter blue represents operators and operands in your code. As =, ||, + and *.
 rgss_lesson5.jpg ( 3.52k ) Number of downloads: 1011


Green
The color green represent your comments. Comments are ignored from your code, it's like your note about what you are doing and what the code does.
 rgss_lesson6.jpg ( 8.47k ) Number of downloads: 1120


Purple
Purple represent text (string) elements in your code, along side with the directory symbol of Ruby.
 rgss_lesson7.jpg ( 2.51k ) Number of downloads: 463


Script Editor Features:

The script editor of RPG Maker XP come with some basic features, as Search, Replace and Go To Line. Here's a list of those options.

Code View Features:
(Right-Click in the Code View window to see all the features)

-> The basic Cut/Copy/Paste/Undo from Windows are available.
-> Find (Control+F)
-> Replace (Control + H)
-> Go To Line (Control + G)
-> Zoom IN/OUT with Control+Mouse Wheel

Page List Features:
(Right-Click in the Page list View window to see all the features)

-> The basic Copy/Paste/Cut from Windows are available
-> Add a page (Insert)
-> Delete a page (Delete)
-> Find (Control + F)

There are also some small options in the "Page Name" section, to the bottom left of the window, that allow you to set the text alignment and use unicode characters; this is probably there because RPG Maker XP is a japanese product.

6- Basic vocabulary and syntax

Now comes the time to dig up some code, very basic one, in order to show the primary syntaxes and terms you will uses in almost all your scripts. Let's begin by a simple program that upon execution, will simply print on screen the word "I am therefore I'm coded.". (I'm sorry to break the rule of the "Hello World" convention, but we needed a change !

CODE

class Say_Something
  
   def initialize
     print "I am therefore I'm coded"
   end

end

Create a new page with the script editor, and copy/paste that code in it. Remember, you can name the page whatever you desire, but it is recommended to name it wisely. (Choose a name that represent the script functions. In this case, you could call it Say Something...)

Now, if we want to test that out, we need to create an event on your map that will execute that class. In this event, choose a "Call Script" command (the last option on the last page), and write this in it:

CODE

Say_Something.new

And test play your game, go talk to that event, and a window will pop-up saying "I am therefore I'm coded.".

So here's the explanation for this (line by line):

CODE

1 class Say_Something
2  
3    def initialize
4      print "I am therefore I'm coded"
5    end
6  
7 end

Line 1: We defined a new class named "Say_Something".
Line 3: We defined a new method named "Initialize".
Line 4: We added the code to be executed when the method "initialize" is called.
Line 5: We close our method "initialize" with the "END" keyword.
Line 7: We close our class "Say_Something" with the "END" keyword.

The method "initialize" is a default method that is executed when you use the .new syntax, as you did in your event's Call Script. So, when you said in your call script the sentence "Say_Something.new" you told RPG Maker XP to create an instance of Say_Something with the message "new"; which executed the "initialize" method.

You also saw that everything that is "defined" most be closed, with the END keyword. This applies to a lot of things in Ruby, and this is why it's a good idea to always indent your code. (See example of indentation below).

 rgss_lesson8.jpg ( 64.61k ) Number of downloads: 4122


As you can see, we could called each syntaxed that need to be closed as "segments" of code. You can clearly see when each should start and end if your code is well indented.

But we said earlier that everything was an object, and we did not seem to see any "object" while doing our "Say Something" example. Fact is you actually did an object, but it died . You could have written the following in your call script, and everything would have worked fine:

CODE

my_object = Say_Something.new

This would have the same effect, here we see that we created a new object named "my_object" that should be of class "Say_Something". Of course, since our class does nothing except displaying a message, it's kind of useless to specify an object name.

Let's tweak our "Say_Something" class so we can use objects in a better way, and you will also be introduced to "Arguments". Replace the code in "Say_Something" by the following code:

CODE

class Say_Something

attr_accessor :greeting
attr_accessor :name

   def initialize(greeting, name)
     @greeting=greeting
     @name=name
   end

  def say
   print @greeting + " " + @name
  end
  
end

Then, in your event, edit the Call Script you previously did (right-click and choose Edit or press the spacebar.) And replace it's content by this one:
(I made extra line break to better classify the structure of what we do.)

CODE

message1=Say_Something.new("Hello", "Alex")
message2=Say_Something.new("Hello", "Peter")

print message1.name
print message2.name

message1.say
message2.say

Now go test play your game, go talk to that event, you will see 4 pop-up window displaying in turns the element you asked for. The first window will display the name given to the object "message1", the second window will do the same for "message2". Then, 2 other window will pop-up executing the message "say" that we told. "say" is a method in our class "Say_Something".

This means that you just created 2 objects, "message1" and "message2", which are now 2 instances of "Say_Something", that can be modified without altering the other.

Let's explain that code, line by line, once again:

CODE

01 class Say_Something
02
03 attr_accessor :greeting
04 attr_accessor :name
05  
06   def initialize(greeting, name)
07    @greeting=greeting
08    @name=name
09  end
10
11  def say
12    print @greeting + " " + @name
13  end
14  
15 end

Line 1: We defined a new class named "Say_Something".

Line 3: We defined an ATTR value, which stand for Attribute. Ruby is powerful in the sense that we can simply use the ATTR_ACCESSOR syntax to define a new attribute that will be readable and writable for every objects instance created by "Say_Something". So our first ATTR is named "greeting".

Line 4: We defined another ATTR named "name".

Line 6: We defined a new method named "initialize". As we said earlier, the initialize method is the method that is executed first when an object is created by the class. So we added the "Argument Receiver" that this method will be able to receive. In our case, those "argument" (or attribute) are "greeting" and "name". We put those argument receiver between paranthesis aside the method name. Take note that those "Argument Receiver" are "recipients"; by that I mean that the name you used between the paranthesis are variable names; which you have to use later on for it to have a purpose.

Line 7: Here we defined a new "Instance Variable" that will hold the data sent within "greeting". An instance variable always begins with an @ and is useable in every method of the same class, and most be defined in a method. By doing this, we told RPG Maker XP to take the recipient "greeting" and put it inside of "@greeting" to allow us to use it in another method.

Line 8: We do the same as on line 7, but with the "name" attribute.

Line 9: We close our method "initialize" with the END keyword.

Line 11: We defined a new method called "say".

Line 12: We coded what should happen when an object receives a message "say". In our case, we print the content of "@greeting", plus an empty space, plus the content of "@name".

Line 13: We close our method "say" with the END keyword.

Line 15: We close our class "Say_Something" with the END keyword.

Now let's explain the code of the Call Script, line by line, once again:

CODE

1 message1=Say_Something.new("Hello", "Alex")
2 message2=Say_Something.new("Hello", "Peter")
3
4 print message1.name
5 print message2.name
6
7 message1.say
8 message2.say

Line 1: We create a new object called "message1" that will be an instance of "Say_Something". Which means that everything we can do with that object is defined in our class "Say_Something". Since we added "Argument Receiver" in our "initialize" method in "Say_Something", we need to send those argument, or RPG Maker XP will close asking for them. To send an argument to a class, it work the same way as for setting them, you list them in between paranthesis aside the class name.

Line 2: We do the same to create another object named "message2".

Line 4: We use the Ruby command "print" to display the name stored in our object "message1". As you can see, it's simple, you can access objects attributes (properties) by using the name you defined in the ATTR of your class.

Line 5: We do the same for "message2".

Line 7: We now send a message to our object "message1", that message is "say". You can called that a "command" to, if you wish. So, you told "message1" to execute it's function "say"; then "message1" searched in it's class "Say_Something" to see if that command is defined... And it was, so our object returned the actions defined in the class; which is to print something on screen.

Line 8: We do the same for "message2".

7- Conclusion

Now you have the basic knowledge of what is the main structure of a Ruby program, and know all the basic thing you will need to understand Chapter 2 of this lesson; which should be out next week. I'm trying to do one each week.

Don't worry, the following chapters will be mainly about coding, since the basic stuff is already explained. And for those of you who wants the full list of syntax convention, as the difference between each variable type, it will be the first section of my chapter 2. I decided to put it in that chapter and not in this one because chapter 2 will contains a lot of code example, and it's better to have the reference on the same chapter as the main code is.

Feel free to reply with your feedback, and if you have correction to add, just reply so.

This post has been edited by Dubealex: Nov 7 2005, 08:26 PM

[rhspooky]

OH MY GOD
I'm 38 and I just did my first line of script and I knew what the hell was going on

thank you

I think I might enjoy this after all.... now on to chapter 2

rhspooky

[Ricque]

The game crashes when i try to play it after I have made the script "Something_New"


class Say_Something
?
?def initialize
? ?print "I am therefore I'm coded"
?end
?
end


There's a message telling me:

????? 'Say_Something' ? 2 ??? SyntaxError ????????


What's the problem?


EDIT: Ok, I did found the solution on my own. I just turned the ?'s to Space's instead. You should tell the reader that the ? shouldn't be there, becuase the game crashes if they do. I know you did those ?'s becuase of the limits of the forum but I didn't knew it in the first place

[Mat]

The images don't seem to work at the moment, well for me I can't see them at all.

[freakboy]

i dont know if this is the right place, but is there a script to display the hero's name in the menu...? (like \n[1] in the message)

[Crash]

i dont know if this is the right place, but is there a script to display the hero's name in the menu...? (like \n[1] in the message)

Look at RGSS Lessons Chapter 2!
and here is the code:
actor= $game_party.actors[#ID]
self.contents.draw_text (x, y, width, height, actor.name)
** replace #ID with ID of your char in database, and replace x, y, width, height with values you want.

[freakboy]

thanks crash, but i'm having some trouble....
how do i need to put it in?

is it like this?
s2 = "actor= $game_party.actors[1]"
self.contents.draw_text (x, y, width, height, actor.name)

[Crash]

thanks crash, but i'm having some trouble....
how do i need to put it in?

is it like this?
s2 = "actor= $game_party.actors[1]"
self.contents.draw_text (x, y, width, height, actor.name)

First of all where do you want to put it (You should realy take a look at RGSS Lesson Chapter 2)?
But you should replace the line that starts with s2... with
actor= $game_party.actors [ID]
as I told you ID is your character's ID in database, so 1 will be character in database that has ID = 1.
With second line everything is ok, you just have to replace words and letters (width, height, x, y) with values you want to be (also look little reference about x and y coordinates)
.name will simply "put" name of the character stored in variable actor.
I think you get it now... a bit more...

[freakboy]

i tried it, but it says "line 23, undefinied method"
(self.contents.draw_text(0, 0, 100, 32, actor.name)

[Djinnilord]

Just gotta say, this is great.
I've been looking all over the net for a tutorial like this, and then I just see a link at RPGi.
This is really helping me, I think I'm getting the grasp of things now.

Thanks alot, Dub, Al, or whatever your nickname might be (if you have one).

By the way, hello everyone, this is Djinnilord, the GoldenSun freak, the one who's used RmXP for 4 and a half months, the Scripting Newbie, and the one who recently (O_O) joined the forums here.

Greetings.

[Dubealex]

CODE

(self.contents.draw_text(0, 0, 100, 32, actor.name)

This wont work.

CHeck chapter 2, i say how in it.

[Supreme Pie Ninj...]

That tutorial was amazing! I didn't even read it yet and it's still amazing!

Rock on, Alex!

[SigmaX65]

im lost completely. i understand everything up to the stuff about arguments. Its just confusing the hell out of me. i get confused with all the stuff in quotations, the explantions of the code, just about everything! i really really want to learn how to use RGSS, but i just cant get any of the explntions of the stuff. can someone help?!?!

[Hellcat]

Awesome guide Dub, I'm lovin it.

At first I felt pretty overwhelmed by the RGSS, I had done a bit of VB coding, which is actually really similar to this as well, which is going to make this alot easier.

I look forward to mastering this language (as well as the RMXP limited scripted version) as I progress more into this field. Thanks man, this is a awesome guide. Keep up the good work.

[Supreme Pie Ninj...]

I just finished reading this...it's actually starting to sink in!

But I think I should read it again, to better grasp it.

Awesome job!

[XenoZiden]

YAY I get it now.

[Supersonic Yoshi]

Good job!

[SailorSedna]

Wow this is amazing, at least i only have to learn rgss required for rpg maker xp only!




Um the script editor window is so massive i can't see the bottom scroll bar or page name tab, is there a way to make it smaller i tried to change the screen resolution but the max is 1024 x 7...blah blah


please help me

[Dubealex]

if you are using postality edition, the screen is suppose to be ok. In dynaemu, i think you need a resolution fix. You can dowload the reso fix oin XRPG.

[Lawman]

I tried making your first script example titled Say_Something, and I keep getting the same error message

????????NameError????????
Unitialized constant Interpreter ::Say_Something

can you explain what I'm doing wrong please?