# 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](https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) and function exactly the same as they normally do. Alternatively, you can also use symbols named after [the equivalent SDL scancodes](https://wiki.libsdl.org/SDL_Scancode?highlight=%28%5CbCategoryEnum%5Cb%29%7C%28CategoryKeyboard%29) (with the exception of the top-row number keys, which are defined as `:NUMBER_0`, `:NUMBER_1`, `:NUMBER_2`...). ```ruby # 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. ```ruby 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. {% hint style="warning" %} `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. {% endhint %} ```ruby # 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: ```ruby 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](https://www.deviantart.com/kleinstudio/art/DLL-SCRIPT-Klein-Bitmap-Functions-561848552). 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://roza-gb.gitbook.io/mkxp-z/extensions/rgss.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.