Skip to content

Functions & Usage

rkevin edited this page Feb 23, 2021 · 2 revisions

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.
  • 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.
  • You can make a sprite wavy by using sprite.wave_amp, sprite.wave_length, sprite.wave_speed, and sprite.wave_phase. TODO: Write better documentation for this, but pancakes knows this better than I do.
  • TODO: document sprite.bush_opacity.

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 remote 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. TODO: more documentation on this.