RGSS Roadguide

[Trickster]

RGSS Roadguide
Your Detailed Roadmap to the RGSS library
By Trickster
Proofreading by PK8 and BloodSpawn.

Introduction
First and foremost RGSS is not a programming langauge. Many are confused on what RGSS actually is. RGSS is a library written in C that extends the programming langauge Ruby, and RGSS is an acronym for Ruby Game Scripting System. It is used within RMXP and provides Graphics, Audio, and Input functions for Ruby.

How to use this guide
Reading this will not teach you how to script. However, if you know how to script then this guide will improve your scripting for RMXP. This guide just goes over the classes, methods, and limitations of RGSS. I will state each class and all of its methods example calls and common pitfalls that you should look out for when using. This is intended to explain the RMXP helpfile for this information.

Method documentation will appear as follows:
method: method_name(<required parameters>, optional parameters)
description: This is a method RAWR!
parameters: An explanation of what class each parameter needs to be and what it does.
example calls: Acceptable calls to the method with visuals when necessary
comments: Comments from the wise one Trickster himself. I will tell you how useful or how crappy the method is. Things to watch out for and other stuff.
So what's included in RGSS?

• Classes
  • Bitmap
    
  • Color
    
  • Font
    
  • Plane
    
  • Rect
    
  • Sprite
    
  • Table
    
  • Tilemap
    
  • Tone
    
  • Viewport
    
  • Window
    
  • RGSSError
    
  • RPG::Sprite
    
  • RPG::Weather
    
  
  
• Modules
  • Audio
    
  • Graphics
    
  • Input
    
  • RPG
    
  • RPG::Cache
    
  
  
• Methods
  • load_data
    
  • save_data
    

Bitmap

Bitmap

This class is synonymous with an image. You may perform image manipulation methods on these to modify the image. They can not be displayed on the screen by themselves.

Note: For reference in my visuals avatar.png is this image and ruby.png is this image and doll-image.png is this image



Method List
method: Bitmap.new(filename)
description: Attempts to load an image. This method can load images from encrypted archives. This method returns a bitmap with that image. Image extensions may be omitted.
parameters: Filename is a string representing the filename or a path to the filename
comments: Please don't use this method unless it is absolutely necessary or you know what you are doing. It would be better to just use RPG::Cache. RPG::Cache keeps track of the images loaded and using that won't be as taxing on speed and memory.
example calls:

Code:

Bitmap.new("avatar")

->

Code:

Bitmap.new("C:/Documents and Settings/Trickster/Desktop/ruby.png")

->




method: Bitmap.new(width, height)
description: Creates a new fresh bitmap with these dimensions. The bitmap created from this method will be clear with nothing drawn in it nothing.
parameters: The two parameters width and height are positive, non-zero integers.
comments: This method is laggy try not to call it too many times within a frame. The bigger the size of the bitmap created the longer it takes to create it.
example calls:

Code:

Bitmap.new(32, 32)

Code:

Bitmap.new(640, 480)

method: dispose
description: Frees the bitmap. However, once freed you may not do use any image manipulation methods on it.
parameters: NA
comments: Always use this method when you are done with a bitmap or else you will suffer memory leaks. If you try to use a bitmap function, for example, draw_text on a disposed bitmap then you will get an error (RGSSError).
example calls: NA




method: disposed?
description: A query method used to check if a bitmap has been disposed.
parameters: NA
comments: NA
example calls: NA




method: width
description: Gets the bitmap's width
parameters: NA
comments: NA
example calls:

Code:

Bitmap.new('doll-image').width # returns 128

method: height
description: Gets the bitmap's height
parameters: NA
comments: NA
example calls:

Code:

Bitmap.new('doll-image').height # returns 192

method: rect
description: Gets the bitmap's rect
parameters: NA
comments: This method returns a Rect of its dimensions, that is, (0, 0, width, height)
example calls:

Code:

Bitmap.new('ruby').rect # returns Rect.new(0, 0, 83, 85)

method: blt(x, y, source_bitmap, source_rect, opacity)
description: Block Transfer. Copies all or part of source_bitmap onto the bitmap this is called on (the destination bitmap).
parameters: Method parameters x and y defines the top coordinate of where the source bitmap is drawn onto the destination bitmap. Parameter source_bitmap is another bitmap object use as the source. Parameter source_rect is a rect object specifying the bounding box of the area of the source bitmap to transfer. Parameter opacity is an integer [0, 255] representing the transparency of the bitmap drawn. Opacity is assumed to be 255 when it is omitted
comments: This method is pretty fast and is one of the most useful methods of this class.
example calls:

Code:

bitmap = Bitmap.new(320, 240)

src_bitmap = Bitmap.new("avatar.png")
bitmap.blt(0, 0, src_bitmap, src_bitmap.rect)

Does this

Code:

bitmap = Bitmap.new(160, 160)
bitmap.fill(bitmap.rect, Color.new(0,0,0))
src_bitmap = Bitmap.new("doll-image.png")
src_rect = Rect.new(0, 0, src_bitmap.width / 2, src_bitmap.height / 4)
bitmap.blt(0, 0, src_bitmap, src_rect, 128)

Does this




method: stretch_blt(dest_rect, source_bitmap, source_rect, opacity)
description: Stretch Block Transfer. Copies all or part of source_bitmap onto the bitmap and stretches it to fit dest_rect this is called on (the destination bitmap).
parameters: Method parameter dest_rect is a Rect object setup to have the position relative to the source bitmap of where the bitmap is drawn and the dimensions to stretch the source bitmap to. Parameter source_bitmap is another bitmap object. Parameter source_rect is a rect object specifying the bounding box of the area of the source bitmap to transfer. Parameter opacity is an integer [0, 255] representing the transparency of the bitmap drawn. Opacity is assumed to be 255 if omitted
comments: This method is also pretty fast and is one of the most useful methods of this class.
example calls:

Code:

bitmap = Bitmap.new(160, 160)
bitmap.fill(bitmap.rect, Color.new(0,0,0))
src_bitmap = Bitmap.new("doll-image.png")
dest_rect = Rect.new(32, 32, 0.75 * src_bitmap.width, 0.5 * src_bitmap.height)
src_rect = Rect.new(0, 0, src_bitmap.width / 2, src_bitmap.height / 4)
bitmap.stretch_blt(dest_rect, src_bitmap, src_rect, 64)

Does this




method: fill_rect(x, y, width, height, color) or fill_rect(rect, color)
description: Fills an area of the bitmap with a color.
parameters: In the first call Integers x, y, width, and height specifies the bounding box of the area to fill; in the second call rect specifies the bounding box. Parameter color is the color of the area to fill.
comments: This method does not cause lag, but it will if you call it continuously for very large areas.
example calls:

Code:

bitmap = Bitmap.new(160, 160)
bitmap.fill_rect(bitmap.rect, Color.new(0, 0, 255))
bitmap.fill_rect(60, 70, 40, 60, Color.new(255, 0, 0))

Does this





method: clear
description: clears the entire bitmap object
parameters: NA
comments: Useful and faster than using fill_rect to clear the bitmap
example calls: NA




method: get_pixel(x, y)
description: Gets a color at a point of the bitmap. It returns a Color object representing the color at that specified point.
parameters: Integer X and Y defines the point of where to extract the color.
comments: This method is fast, but calling it many many times especially on a large bitmap will cause lag.
example calls:

Code:

Bitmap.new(1,1).get_pixel(0, 0) # returns Color.new(0, 0, 0, 0) (clear)

Code:

Bitmap.new("avatar").get_pixel(80, 140) # returns Color.new(127, 117, 188)

method: set_pixel(x, y, color)
description: Sets a color at a point of the bitmap.
parameters: Integer X and Y defines the point of where to set the color, and color is a Color object representing the color to set at that point.
comments: same as get_pixel
example calls:

Code:

bitmap = Bitmap.new(10, 10)
10.times do |i|
  10.times do |j|
    bitmap.set_pixel(i, j, Color.new(i * i, 2 * i * j, j * j))
  end
end

Does this this is pretty don't you think?

Code:

bitmap = Bitmap.new("avatar.png")
bitmap.height.times do |i|
  bitmap.set_pixel(100, i, Color.new(0, 0, 0, 0))
end

Does this




method: hue_change(hue)
description: Changes the hue of the bitmap.
parameters: Integer hue a value in the range [0, 360]
comments: THIS IS A CRAP METHOD. FOR THE LOVE OF GOD DO NOT CALL THIS EVERY FRAME. DO NOT CALL THIS ON LARGE BITMAPS. DO NOT CALL THIS MULTIPLE TIMES ON THE SAME BITMAP. This is the most laggiest function for the bitmap class. Find a way around using this method, because it is time consuming.
example calls:

Code:

bitmap = Bitmap.new(10, 10)
10.times do |i|
  10.times do |j|
    bitmap.set_pixel(i, j, Color.new(i * i, 2 * i * j, j * j))
    bitmap.hue_change(10) #this is dangerous see comments
  end
end

Does this

Code:

bitmap = Bitmap.new(10, 10)
10.times do |i|
   10.times do |j|
     bitmap.set_pixel(i, j, Color.new(i * i, 2 * i * j, j * j))
   end
end
bitmap.hue_change(10)
#the above isn't dangerous this is not being called 100x now

Does this

Code:

bitmap = Bitmap.new(10, 10)
  10.times do |i|
    10.times do |j|
      bitmap.set_pixel(i, j, Color.new(i * i, 2 * i * j, j * j))
    end
  bitmap.hue_change(10) #A bit dangerous
  end

Does this




method: draw_text(x, y, width, height, string, align) or draw_text(rect, string, align)
description: Draws a string on the bitmap.
parameters: Integer x, y, width, and height defines the bounding box for the string to be drawn. string is a String object which is the text to be drawn. Integer align is either 0 for left align 1 for centered 2 for right align. If the align parameter is omitted then the text will be drawn left aligned
comments: This method is laggy, but it isn't as laggy as hue_change. Do not call this method every frame or you will get lag. If the string is too big to be drawn in the bounding box then it will be shrunken (by upto 60%) so that it can fit This is shown in example call 4. A common pitfall with this method is that when people are trying to draw centered or right aligned text they screw up the width parameter and it doesn't center correctly. This is shown in example call 5.
example calls:

Code:

bitmap = Bitmap.new(160, 32)
bitmap.fill_rect(bitmap.rect, Color.new(255, 255, 255))
bitmap.font.color = Color.new(0, 0, 0) # Sets the color of drawn text
bitmap.draw_text(0, 0, 160, 32, 'Hello World')

Does this

Code:

bitmap = Bitmap.new(160, 32)
bitmap.fill_rect(bitmap.rect, Color.new(255, 255, 255))
bitmap.font.color = Color.new(0, 0, 0) # Sets the color of drawn text
bitmap.draw_text(0, 0, 160, 32, 'Hello World', 1)

Does this

Code:

bitmap = Bitmap.new(160, 32)
bitmap.fill_rect(bitmap.rect, Color.new(255, 255, 255))
bitmap.font.color = Color.new(0, 0, 0) # Sets the color of drawn text
bitmap.draw_text(0, 0, 160, 32, 'Hello World', 2)

Does This

Code:

bitmap = Bitmap.new(160, 32)
bitmap.fill_rect(bitmap.rect, Color.new(255, 255, 255))
bitmap.font.color = Color.new(0, 0, 128) # Sets the color of drawn text
bitmap.draw_text(0, 0, 160, 32, 'Trickster Owns SephirothSpawn!!!', 1)

Does This

Code:

bitmap = Bitmap.new(160, 32)
bitmap.fill_rect(bitmap.rect, Color.new(255, 255, 255))
# Sets the color of drawn text
bitmap.font.color = Color.new(0, 0, 0)
width = bitmap.text_size('Hello World').width
# doesn't do what you expect!
bitmap.draw_text(0, 0, width, 32, 'Hello World', 1)

Does this unfortunately




method: text_size(string)
description: Gets the text size of the string if it were to be drawn using draw_text
parameters: string is a String object representing the text to be drawn.
comments: Unlike draw text this method is not laggy. Be warned as this method returns a Rect with its dimensions. Unfortunately you need a bitmap object to call this method, this method should have been a class method of the Bitmap class.
example calls:

Code:

Bitmap.new(32, 32).text_size('Hello World') # returns Rect.new(0, 0, 99, 22)

property: font
description: The font object used for drawing text using the draw_text method (see the Font class)
Ok the Bitmap class is done over the weeks I shall create posts for the other classes enjoy this one for now and this is a preview for those to come.

Note: If I ask you to code a one line statement for a question be sure to space out arguments like this

method(param1, param2, param3, param4)

since it is looking for an exact answer anyway you should do it this way it looks neater =P

Color

Color

This is a RGBA color class, this class handles colors though there is not much you can do to a Color object. I would also point out that class is a Structure class since the only thing you can do is access and mutate its instance variables.




method: Color.new(red, green, blue, alpha)
description: Creates a new color object
parameters: Numeric values red, green, and blue are within the range [0, 255] and specify their respective color values. Numeric value alpha is the opacity value 255 for fully opaque and 0 for fully transparent, when left off it is assumed to be 255.
comments: NA
example calls:

Code:

Color.new(255, 255, 255) #this is white
Color.new(255, 255, 0) # this is yellow
Color.new(0, 0, 0, 0) #this is clear
Color.new(70, 70, 70, 128) #a semi transparent gray like color
Color.new(0.5, 12.9, 192.99) # this is also valid - some bluish color

method: set(red, green, blue, alpha)
description: Sets all color values
parameters: [/color][/color]Numeric values red, green, and blue are within the range [0, 255] and specify their respective color values. Numeric value alpha is the opacity value 255 for fully opaque and 0 for fully transparent, when left off it is assumed to be 255.
comments: Useful if you just need to change the color without creating a whole new Color object for it
example calls:

Code:

color = Color.new(0, 0, 0)
color.set(255, 255, 255) #now I'm white
color.set(0, color.green, 128) # a lite green color
color.set(color.green, color.blue, color.red) # orange!
color.set(color.red, color.green, color.blue, 0) #clear

property: red
description: The red value of the color


property: green
description: The green value of the color

property: blue
description: The blue value of the color


property: alpha
description: The opaqueness of the color

Font

Font

This class represents a font. This class is used primarily for bitmaps to control how text is drawn using draw_text. This is another structure class since all you may do is access and mutate its instance variables.




method: Font.new(name, size)
description: Creates a new font object.
parameters: Name is a string that specifies the font name, make sure that the font name exists in your system and in the system of the users machine. The Default for if this parameter is omitted links to Font.default_name. Size is an integer value if it is omitted then the default value of pointed to by Font.default_size will be used
comments: This method doesn't really have any use, there is no need to use this method as when you create a Bitmap a font is automatically created with it.
example calls:

Code:

Font.new("Arial", 22)
Font.new
Font.new("Crystal")

method: Font.exist?(name)
description: Checks if the font exists in the system.
parameters:[/color][/color] Name is a string that represents the name of the string to check.
comments: Pretty useful for checking if the font exists in the end users system and reporting a message to them that they need to install the font.
example calls:

Code:

Font.exist?("Times New Roman")
Font.exist?("zzyzzous")
Font.exist?("My Font Here")
Font.exist?("Arial")

property: name
description: The name of the font being used


property: size
description: The size of the font being used.


property: bold
description: The bold flag. If this is true then text drawn will be bold.


property: italic
description: The italic flag. If this is true then text drawn will be italicized. Be warned though that calling text_size with this flag on will return an incorrect value since italics is not counted for in that method.


property: color
description: The color of the text drawn.


property: Font.default_name
description: The default name for all newly created font objects if the name wasn't specified when you create it. If a bitmap object is created then a new font will be created with the name pointed to by this property.


property: Font.default_size
description: The default size for all fonts when a new font is created the size value (unless specified) will be this value.


property: Font.default_bold
description: The default bold flag. All fonts created will have their bold flag set to this value.


property: italic
description: The default italic flag. All fonts created will have their italic flag set to this value.


property: color
description: The default color of the text drawn. All fonts created will have their color set to this.