RGSS

Kernel

  • load_data now has a second optional Boolean argument which, if set to true, returns the raw bytes of the file as a String. Normally, people tend to override Marshal functions in order to accomplish the same thing. Now you don't have to.

Input

Extra button/key state functionality

Input.release? can check for whether a button has been released between the last two calls to Input.update.

Taken straight from Pokemon Essentials, Input.pressex?, Input.triggerex?, Input.repeatex? and Input.releaseex? use Windows Virtual-Key codes and function exactly the same as they normally do. Alternatively, you can also use symbols named after the equivalent SDL scancodes (with the exception of the top-row number keys, which are defined as :NUMBER_0, :NUMBER_1, :NUMBER_2...).

# Microsoft VKey-codes
Input.pressex? 0x01 # Left mouse button
Input.triggerex? 0xa1 # Left Shift

# SDL Scancode names
Input.repeatex? :BACKSPACE
Input.triggerex? :F5

To detect the amount of time a key has been held down, Input.time? and Input.timeex? return the amount of time the currently repeating key has been held, in microseconds.

Getting text input

If Input.text_input is set to true, mkxp-z will begin receiving text input events. To use these, call Input.gets. It will return any text that was received since the last time Input.gets was called.

The Input.clipboard property gets and sets the user's clipboard.

text = ""
Input.text_input = true

while !Input.pressex?(:RETURN)

    if Input.pressex?(:LCTRL) || Input.pressex?(:RCTRL)
        Input.clipboard = text if Input.triggerex?(:C)
        text += Input.clipboard if Input.triggerex?(:V)
    else
        text += Input.gets
    end
    
    Input.update
    Graphics.update
end

Input.text_input = false
p text

Mouse Input

Input.mouse_x and Input.mouse_y return mouse coordinates. They are scaled to match the screen's size, if necessary.

For mouse buttons, you can feed Input::MOUSELEFT, Input::MOUSEMIDDLE, and Input::MOUSERIGHT to Input.press? or its ilk.

Controllers

Input.joystick can be used to detect connected joysticks. If it is nil, there is nothing connected. Otherwise, it will return a hash. Input.joystick[:name] contains the joystick's name, and Input.joystick[:power] contains the joystick's power level. This can be anything from :MAX, :WIRED, :HIGH, :MEDIUM, :LOW, :EMPTY and :UNKNOWN.

Controller binding is supported through the F1 menu.

Graphics

Window Resizing & Fullscreen

  • Graphics.scale is a property that gets and sets the scale of the window based on its rendering resolution. (between 0.5 and 2)

  • Graphics.fullscreen is a property that gets and sets the current fullscreen state (true or false)

  • Graphics.center places the window in the center of the screen.

  • Graphics.resize_screen is available from VX regardless of RGSS version, along with the other functions introduced in VX and VX Ace.

Play Movie

mkxp-z supports playing videos in Ogg Theora (.ogv) format through Graphics.play_movie, regardless of RGSS version. The letterbox and video itself are both actually sprites with the z-levels 4999 and 5001; so sprites may be placed in-between (5000) or in front of (5002+) the video.

play_movie is processed completely by the CPU; avoid high bitrates, framerates, or resolutions if you can, especially combinations of the three. You will witness lag and strange behavior if you do not.

# Just play a video, skippable with Input::C or Input::B by default
Graphics.play_movie("cutscene.ogv")

# Play a video, volume 60%, disallow skipping
Graphics.play_movie("cutscene.ogv", 60, false)

Taking Screenshots

Graphics.screenshot(path) will take a screenshot and save it to path in BMP format.

Telling Time

Graphics.delta returns the amount of time passed since the last call to Graphics.update (in microseconds).

Graphics.average_frame_rate gives the "real" framerate -- how long it took for the past several calls to Graphics.update to complete, including all the time taken running code in between calls. This is the same number shown by pressing F2, as a float.

Bitmap

GIF Playback

If a Bitmap is created from a gif that contains multiple frames, it is automatically converted into an animated bitmap. Framerate and loop information are set automatically. All you should need to do is:

spr = Sprite.new
spr.bitmap = Bitmap.new("some.gif")
spr.bitmap.play if spr.bitmap.animated?

Or, if you want to do something more complicated, read about animation below.

Animation

All non-megasurface bitmaps support multiple frames of animation. Animated bitmaps are primarily meant to be played and not changed, and do not support most editing operations.

Individual frames given and returned by these functions are 0-indexed.

Accessing animation information

  • animated? returns true if the bitmap is animated (possesses more than one frame).

  • playing is a property that gets and sets whether or not the bitmap is currently playing. It automatically returns false if looping is also false and the bitmap has reached its last frame of animation. All Bitmaps begin stopped.

  • looping is a property that gets and sets whether or not the bitmap should loop indefinitely. true by default.

  • current_frame returns the frame that the bitmap currently depicts.

  • frame_count returns the total number of frames contained in the bitmap.

  • frame_rate is a property that gets and sets the intended playback speed of the bitmap. This is a float, so it can be as precise as you like (e.g. 29.97 or 59.94). Defaults to 0.

Automatic Playback

  • play will begin asynchronous playback of the bitmap.

  • stop will pause playback of the bitmap.

Manual Control

  • goto_and_stop(position) will move to the frame specified with position. goto_and_play(position) Will do the same, and begin playback from there.

  • next_frame advances the bitmap to its next frame. This will cycle from beginning to end if looping is set to true. Returns the index of the frame that the bitmap has moved to. Stops the bitmap if it is playing.

  • previous_frame moves the bitmap back one frame. This will cycle from end to beginning if looping is set to true. Returns the index of the frame that the bitmap has moved to. Stops the bitmap if it is playing.

Timeline Editing

  • add_frame(source[, position]) adds a new frame using the Bitmap specified at source. By default, the new frame will be appended to the end of the animation, but the destination index can be specified with position. This converts the bitmap into an animated bitmap if it was not one already -- if frame_rate is currently 0 in this case, it is changed to match Graphics.frame_rate.

  • remove_frame([position]) removes the frame at the index specified with the optional position. Defaults to removing the last frame in the timeline. Only works on animated bitmaps, and changes them back into a normal bitmap if there is only one frame left after the operation.

Manipulating Frame Data

These functions require the bitmap to be stopped. They operate on whatever frame the bitmap is currently displaying. Animated bitmaps are not currently cached for reading, so functions that read from an animated bitmap are just as expensive as functions that write to one.

  • snap_to_bitmap([position]) captures the currently displayed frame (or the frame specified by position if it's provided), and returns a new Bitmap created from it. (This is compared to using something like dup to copy the bitmap, which copies all frames)

  • Blitting, using the raw_data property, and saving the bitmap to a file should also work on animated bitmaps.

Accessing Bitmap Data

To access bitmap data directly, Bitmap.raw_data is a property that will get and set a string containing the Bitmap's data in RGBA8 format.

When setting bitmap data, the string's byte size must be equal to the bitmap's width * height * 4. If this isn't the case, an MKXPError will raise.

Saving to File

To save a bitmap directly to a file, to_file(path) has been added. It will save a Bitmap to wherever path specifies in BMP, PNG or JPEG format, depending on the extension given.

Audio, Sprite

Like the Graphics module, functions and properties normally only available in newer versions of RGSS have been made available in RGSS1/XP mode. In addition to this, Sprites have a number of new functions:

Pattern Overlays

Patterns can be applied to a Sprite as an additional way to add effects. Patterns are just bitmaps which overlay the sprite's base bitmap; there are a few options to be set to configure them as well, but that's the gist of it. It should work similarly to how it does here. It should also work perfectly fine with animated bitmaps, in case you happened to wonder.

New Sprite Properties

  • pattern: A property, similar to bitmap, that points to a Bitmap object to use as the sprite's pattern.

  • pattern_blend_type: A property, similar to blend_type, indicating the blend mode to use when mixing the pattern with the base bitmap. It accepts the same values.

  • pattern_tile: A boolean indicating that the pattern should not be automatically zoomed to fit the rest of the sprite. If you would prefer it the other way, this can be set to false and save a few CPU cycles from doing the math with pattern_zoom_x/y yourself.

  • pattern_opacity: An integer ranging from 0-255, indicating how opaque the pattern should be when mixed over the base bitmap.

  • pattern_scroll_x/pattern_scroll_y: An integer specifying the X and Y positions of the pattern.

  • pattern_zoom_x/pattern_zoom_y: A float specifying the pattern's scaling values.

  • invert: A boolean that allows inverting the color of everything visible on the sprite.

PreviousBuilding with XcodeNextSystem

Last updated