Functions

Here's a list of features ModShot has added that you can invoke from Ruby.

ModWindow module (change window bindings)

• ModWindow.GetWindowPosition returns an array of two elements indicating the X and Y coordinates of the window ([0,0] means the window is in the top left corner).
• ModWindow.SetWindowPosition(x,y) sets the current window position.
  • NOTE: This behaves differently on Windows and Linux. On Windows, this will freeze the game for around a frame, essentially cutting your FPS by half if you call it continuously every frame. On Linux, this will return instantly, so if you want to smoothly move the window you have to call sleep(0.02) or equivalent to make sure you aren't setting the position many times in the same frame.
• ModWindow.SetTitle(title) takes in a string and sets the window title to it. Note: You cannot use string substitution directly, you need to use eval to do so.
• ModWindow.SetIcon(path) takes in a file path to an image, and changes the window icon to it. Be sure to use a relative path from the executable, and include the file extension.

Audio module

The following APIs are a work in progress and will be added to Modshot-Core in a future PR.

The following APIs have been changed:

• Audio.bgm_play(filename, volume = 100, pitch = 100, pos = -1, fadeInOnOffset = true)
  • Added the pos parameter.
    • If this is nonnegative, the music will start playing from this position (measured in seconds).
    • If this is zero, it will start playing the track from the beginning, even if we are currently playing the same track.
    • If this is negative, the default behavior is kept (if filename is different, play new track. if filename is the same, only update volume and pitch).
  • Added fadeInOnOffset parameter.
    • By default, if you set the pos parameter to a nonnegative number, the audio will fade in over 1 second. Set this to false if you don't want this behavior.
  • Audio.bgs_play and Audio.me_play also work the same way.

The following APIs have been added:

• Audio.bgm_playing? returns a boolean (whether the BGM is playing or not).
  • Audio.bgs_playing? and Audio.me_playing? also work the same way.
• Audio.bgm_pos returns a float (the current playback position, in seconds).
  • Audio.bgs_pos also works the same way.
• Audio.bgm_crossfade(filename, time = 2, volume = 100, pitch = 100, pos = -1)
  • This acts similar to the Audio.bgm_play function, except it crossfades between the currently playing track and the new one over time seconds.
  • Audio.bgs_crossfade and Audio.me_crossfade also work the same way.
• Audio.bgm_add_filter and Audio.bgm_clear_filters allow you to add / clear audio filters to the currently playing track. See the audio filters page for more details.
  • Audio.bgs_add_filter, Audio.bgs_clear_filters, Audio.me_add_filter and Audio.me_clear_filters also work the same way.

Sprite module

• You can flip a sprite vertically by setting sprite.vmirror = true. You can get and set this attribute. Pancakes note: It works exactly like the mirror flag. There aren't all too many quirks with it.

• You can make a sprite wavy by using sprite.wave_amp, sprite.wave_length, sprite.wave_speed, and sprite.wave_phase. Pancakes note: As is waves can seriously lag the game especially when it applies to large amounts of sprites. I would HIGHLY recommend avoiding using it when displaying in excess of 200 sprites. A lot of this lag does come from the large amount of sprites onscreen and not from the waves (especially if said sprites are mapped to events) so I would recommend trying to create "bundles" of sprites if possible. Speaking from personal experience, you want to avoid lots of sprites, very large bitmaps, and/or constantly swapping those bitmaps. For example in a reflection script that makes use of them, the game can chug a lot when visiting parts of the barrens or glen because of the sheer amount of events there. One way to combat this is to apply a filter to what reflections display to cut down (often significantly) the number of waving sprites showing. Culling can also help but not by much.

• sprite.bush_opacity Pancakes note: I assume this controls the opacity of tiles (or events?) when displaying behind a "bush" tile. Bush tiles are just tiles that have the top half transparent, as far as I can tell.

Other ruby related changes

• The ./lib/ruby directory is automatically added to $LOAD_PATH, and Modshot ships the ruby standard library as well. You can also "install" your own gems into this directory by copying them over. Make sure that if you have require 'abc' in your code, you have a ./lib/ruby/abc.rb file with the game.

  • For details on how gems with a C extension would work, please contact rkevin for details.

• The ./ssl folder ships with the default CA certificates from Mozilla, allowing you to use TLS and HTTPS. Do not remove this folder unless you don't need TLS/HTTPS.

• ModShot supports GameJolt integration and Discord Game SDK integration available separately. Please check their respective documentation for more details.

• Graphics.update now no longer locks the Ruby GVL. This makes multithreading in Ruby more efficient.- You can merge scripts/Interpreter_1.rb and scripts/Interpreter_7.rb into your interpreter scripts to execute fibers inside your events asynchronously. Fiber documentation

• MKXP.allow_force_quit is a new flag that allows you to violently kill the game when pressing F3. Note: Can cause save corruption. User discretion advised.