Forem: Justin

Brakeman LSP Support

Justin — Fri, 10 Jan 2025 19:34:43 +0000

Announcing the ruby-lsp-brakeman project!

This new gem allows Brakeman scans to be integrated into code editors via ruby-lsp. Scans will run asynchronously in the background and warnings will can be shown inline in the editor.

Using Ruby-LSP-Brakeman

Add ruby-lsp-brakeman to your Gemfile:

gem 'ruby-lsp-brakeman', require: false

In VS Code

If using with VS Code, make sure to install the Ruby LSP extension.

bundle install and then restart the Ruby LSP extension to enable the add-on.

To double-check that Brakeman is running, examine the output tab in the VS Code panel for output like:

[info] (example-app) Finished initializing Ruby LSP!
[info] (example-app) [Brakeman] Activated Ruby LSP Brakeman, running initial scan
[info] (example-app) [Brakeman] Initial Brakeman scan complete - 0 warnings found

When files are saved, there should be logs like:

[info] (example-app) [Brakeman] Queued example-app/app/controllers/some_controller.rb
[info] (example-app) [Brakeman] Rescanning example-app/app/controllers/some_controller.rb
[info] (example-app) [Brakeman] Rescanned example-app/app/controllers/some_controller.rb
[info] (example-app) [Brakeman] Warnings: 0 new, 1 fixed, 2 total

Findings will show up with squiggly underlines:

Background Information

Just for those interested in what's going on behind the scenes!

Language Server Protocol

Language Server Protocol (LSP) is a standard for communication between code editors and code-related tools. It enables tools to hook into standard events for code review, code completion, formatting, etc.

In the Ruby world, Shopify's ruby-lsp provides a convenient implementation of LSP and the ability to build "add-ons" like ruby-lsp-brakeman.

How Brakeman is Integrated

The Brakeman add-on primarily hooks into the file change monitoring, which is triggered when a file is saved or deleted. The file is then added to a queue for rescanning. All files in the queue will be rescanned in the next scan. This is to avoid either triggering multiple concurrent scans or missing file updates because a scan was already in progress.

When the scan is complete, the warnings are reported back as a "diagnostic" to be displayed in the editor.

Interestingly, it's also necessary to return empty sets of diagnostics (per changed file) to clear any fixed warnings that were previously reported.

Brakeman Rescanning

Unlike some other code review or formatting tools, Brakeman works across the entire application, not one file at a time. Code in one file can have effects elsewhere in the application.

A long time ago, "rescanning"/incremental scans were added to Brakeman. To achieve this, Brakeman needs to keep the entire state of the scan in memory, then attempt to update only the relevant information as files change. (This is as opposed to running scans on only a subset of files or caching results offline somehow. Side note: do not use --only-files to try to make this work!)

To know what to update internally, Brakeman would try to guess based on the file that changed (including cascading effects). This was always pretty heavy on heuristics and not very well tested. But it kind of mostly worked!

All the way back in Brakeman 5.0, the scan implementation moved away from using file names and paths to determine the type of file (e.g., controllers vs. models) to using the contents of the file instead. However, the re-scanning was not updated to use this information. Since it was still operating based on file paths, it was no longer aligned with the files being scanned by Brakeman normally.

What all this means is that rescanning has been in a broken and slowly deteriorating state since Brakeman 5.0!

With Brakeman 7.0, rescanning has been revised. For now, rescanning focuses on caching parsed files and only re-parsing changed files. The rest of the scan starts from "scratch". Finding, reading, and parsing files is often one of the slowest parts of scans, so this should still save time for most folks.

Since caching all the parsed files introduces a bit of memory overhead, the functionality is off by default. To enable, initial scans must be run with support_rescanning: true.

Hopefully future work will be able to expand out the "incremental" part of rescanning again.

What's Next

While the add-on generally works with VS Code, I'd love to polish it up a bit more and move to a 1.0 release.

I'm also considering if ruby-lsp-brakeman should depend on Brakeman, or if it should actually be a Brakeman dependency so everyone has it available by default. Let me know if you have thoughts on that.

Please help by testing out ruby-lsp-brakeman and sharing any feedback/bugs!

Tiny E-Ink Picture Display

Justin — Sun, 14 Apr 2024 07:54:54 +0000

After being surprised by the capabilities of a three-color e-ink display (and struggling to get it to work!), I thought I'd put together a little guide.

Hardware

The hardware I used:

Adafruit 2.13 E-Ink Tricolor Display (ThinkInk)
Adafruit ESP32 Feather (ESP32-WROOM-32E)
A micro SD card

In this case, I messed up a little. I already had an ESP32 feather board from Adafruit, so I should have grabbed an e-ink "feather wing" which would have plugged straight into the ESP32 board.

But since I did not do that... here's how I wired up the display:

3V3 (power) to 3V
GND (ground) to GND
SCK (clock) to SCK
MISO to MISO
MOSI to MOSI
ECS to 27
D/C to 33
SRCS to 15
SDCS to 32

The rest I didn't connect.

Note: Don't be tempted to use pins 12 and 13!! Pin 13 is actually shared with the onboard LED, and documentation for pin 12 says "this pin has a pull-down resistor built into it, we recommend using it as an output only".

The names on the board don't quite match the names in the code, so here's a cheatsheet:

#define EPD_DC 33     // D/C
#define EPD_CS 27     // ECS
#define SRAM_CS 15    // SRCS
#define EPD_BUSY -1   // can set to -1 to not use a pin
#define EPD_RESET -1  // can set to -1 and share with chip Reset (can't deep sleep)
#define SD_CS 32      // SDCS

The libraries use defaults for the rest of the pins automatically.

Setting Up Pictures

To fit the display exactly, pictures should be 250 pixels x 122 pixels. However, the display will crop as needed.

I used Gimp and ImageMagick to make the pictures, but the main thing is the images need to be 24-bit bitmaps. I couldn't get Gimp to save images directly to a working format.

Here are the steps I took:

In Gimp, crop and resize to 250x122 pixels (I prefer to crop, resize to 250 pixels wide, crop again to 122 pixels high.)
Set palette:
- Go to Image → Mode → Indexed...
- Select "black and white 1 bit palette"
- OR create a new black/red/white palette and use that
- Choose a dithering option that looks good

As far as the color to use for "red", I believe as long as it has the r value of 255, it will work.

Then...

File → Export As...
Rename to end in .bmp and save

Then...

From the command line, run

convert your_image.bmp -type truecolor your_image_24.bmp

Upload

Save the pictures to the root directory of a micro SD card, then put the card in the display (for me, it's text "down"). The slot is spring-loaded, so just push on the end to eject.

Arduino

I used the Arduino IDE (2.3.2).

For the board type, use "Adafruit ESP32 Feather". (This may seem obvious, but it took me a while to figure out which to use!)

These are the libraries I used (via the IDE's Library Manager):

Code

Full code is available here!

Other good examples to start from:

You'll want to adjust the pin definitions like I did above if you are following along.

ThinkInk_213_Tricolor_RW is the right type to use for the display above.

In my code, I stripped out anything not related to loading and displaying images from the SD card. If you are doing something different, try looking at the other examples.

Update these lines with the names of your images!

  int num_images = 4; // Update with number of images

  // List image paths
  char *images[num_images] = {
    "/image1.bmp",
    "/image2.bmp",
    "/image3.bmp",
    "/image4.bmp",
  };

The program will cycle through the images and update every 5 minutes (or whatever you change the delay to - recommended minimum is 3 minutes).

Results

Here are some examples. Images look best from a little distance.

No Power?!

Yep, the main cool thing about an e-ink display is that they don't need power to maintain the image.

However, I found just removing power from the ESP32 would cause the red pixels to "bloom" and make everything a bit pink.

To prevent this, just disconnect power from the display first. It's possible there is a way to fix this in the code - let me know if you figure it out!

Have Fun!

DragonRuby on Android

Justin — Tue, 12 Mar 2024 07:06:52 +0000

This is a little less-polished-than-usual post about how to build/install Android applications with DragonRuby Pro. on a Linux system. The higher tiers of features in DragonRuby tend to be less well-documented, so here is a bit of a braindump on getting games running on a real Android device.

(Mostly to remind myself how I did all this.)

Building the Package

To be clear, you will need the "Pro" version of DragonRuby to follow this guide.

Running

dragonruby-publish --package

will generate binaries and packages for all supported platforms and dump them in builds/.

Signing

Creating a Keystore

Following the DragonRuby documentation, create a keystore file like this:

keytool -genkey -v -keystore YOUR_APP.keystore -alias your_app_name -keyalg RSA -keysize 2048 -validity 10000

This will generate a file called YOUR_APP.keystore.

keytool is probably already on your system, but if not you'll need to install a Java JDK package using your system tools.

Getting apksigner

To install the package on your Android device, you'll need to sign the .apk build using apksigner. I'm only going to cover one specific way of getting this program on Linux. Your experience may vary.

The easiest way to get apksigner is probably to install Android Studio and go from there. However, I prefer doing things the hard way (and not installing a whole IDE to get one binary...)

First, go to https://developer.android.com/studio/ and scroll allll the way to the bottom to "Command line tools only". Grab the .zip file from there.

Unzip it and find the sdkmanager binary, likely in latest/bin.

Run ./sdkmanager --list | grep build-tools to find the latest version of build-tools.

Then run something like ./sdkmanager --install "build-tools;34.0.0" to install.

The files will probably end up somewhere like ../../../build-tools. In there you'll find apksigner!

Signing the Package

apksigner sign -ks YOUR_APP.keystore builds/YOUR-GAME-android.apk

You'll need to figure out paths for apksigner, YOUR_APP.keystore, etc.

See the official docs for more, especially if publishing to the Google Play store.

Installing on Device

Enable Debug Mode

On your Android device setup developer options, enable USB debug mode, and plug your device into your computer.

Getting adb

The adb tool can be downloaded as part of the SDK Platform tools here: https://developer.android.com/tools/releases/platform-tools#downloads.html

Install the APK

adb install builds/your-game-android.apk

Viewing Logs

To view logs from the device:

adb logcat -e your-game

where your-game is the gameid or packageid configured in mygame/metadata/game_metadata.txt.

Remote Hotload

Building, signing, and installing packages becomes a bit painful if you are doing all that during development.

How about hot-loading code on your Android device just like you can on your development machine?

Setup

When running dragonruby, it opens up a webserver on port 9001. Besides what's obviously visible on the webpage, it's also how your device can connect and load code dynamically.

For that all to work, your development machine and Android device need to be on the same network, and your firewall needs to allow TCP connections on port 9001.

To verify it's working, try opening up your development machines IP on port 9001 from your Android device (e.g., visit https://YOUR.DEV.IP:9001 in a browser).

Building

Run

dragonruby-publish --package-with-remote-hotload

To create a hotloading version of the game, then sign+install like above.

Running

Make sure your are running dragonruby locally on your development machine.

Then open your game on your mobile device - it should flash "Remote hotload enabled" at the bottom if it has been built properly. This does not ensure it actually connected to the development server, though!

To test, try making a visible change to a file on your local machine and see if the change is reflected on the Android device.

Somehow, magically, the hot-loaded changes will persist even through restarts. However, only changes made while the development server is running will be picked up.

Bonus: Detecting the "Back" "Button"

I am old, so I still use the virtual "back" button on Android.

In DragonRuby, this can be detected with

args.inputs.keyboard.key_down.ac_back

For example:

if inputs.keyboard.key_down.ac_back
  gtk.request_quit
end

DragonRuby: Following the Mouse

Justin — Fri, 22 Dec 2023 08:22:16 +0000

Recently I discovered it is very easy to have objects move towards (or away from) any points in DragonRuby.

This post might be a little easier if you've already read my post on moving in arbitrary directions, but actually the code here is even simpler.

If I skip any explanations here, the concepts should have been covered earlier in the series.

Setup

To get started, let's just output a square (roughly) in the middle of the screen.

args.grid.center_x and args.grid.center_y are helpful for this instead of remembering/hardcoding the screen size.

In addition, the code uses args.state.tick_count == 0 to do some setup on the first tick.

def tick(args)
  # On the first tick...
  if args.state.tick_count == 0
    # Create a 50x50 pixel square in the middle of the screen
    args.state.player = { x: args.grid.center_x, y: args.grid.center_y, h: 50, w: 50}

    # Output that square on every tick
    args.outputs.static_solids << args.state.player
  end
end

Pretty basic!

(Note I'm skipping straight to static_solids because that's what I'd prefer in a "real" game.)

Moving to a Point

Now we'll move the "player" to a given point - in this case where the mouse is. In typical DragonRuby fashion, args.inputs.mouse can be used to as a point, even though it has a bunch of other information attached to it.

To get the angle from the player to the mouse, there is a very convenient angle_to method! (Also angle_from depending on which way you'd like to go.)

Just like args.inputs.mouse, the player solid can be treated as if it is a point, too.

One the angle is calculated, vector_x and vector_y will provide the magnitude to move in the x and y directions.

def tick(args)
  if args.state.tick_count == 0
    args.state.player = {
      x: args.grid.center_x,
      y: args.grid.center_y,
      h: 50,
      w: 50
    }

    args.outputs.static_solids << args.state.player
  end

  # Find angle from the square to the current location of the mouse
  angle = args.state.player.angle_to(args.inputs.mouse)

  # Move towards the mouse using the unit vector
  args.state.player.x += angle.vector_x
  args.state.player.y += angle.vector_y
end

And... that's it!! Less than 10 lines of code (without comments/spaces) and it just works.

So now let's make it more complicated...

Centering

It is annoying that the player moves so the bottom, right-hand corner meets the mouse, there is a simple fix: use anchor_x and anchor_y. DragonRuby will automatically use the anchor point for calculations.

To learn more about anchor points, see this earlier post. But typically the values are set to 0.5 which means "middle of the object".

def tick(args)
  if args.state.tick_count == 0
    args.state.player = {
      x: args.grid.center_x,
      y: args.grid.center_y,
      h: 50,
      w: 50,
      anchor_x: 0.5,
      anchor_y: 0.5,
    }

    args.outputs.static_solids << args.state.player
  end

  angle = args.state.player.angle_to(args.inputs.mouse)
  args.state.player.x += angle.vector_x
  args.state.player.y += angle.vector_y
end

Moving to Classes

I continue to prefer taking an object/class-based approach in my own code. This makes it much easier to manage as the code grows larger, even if it seems silly for these small examples.

In a little departure from previous posts, I am not walking through the code in detail. (Please check out my other posts in this series to learn more!)

The main difference from the above is adding a speed to the movement calculation. Other than that, this is how I generally move from simple code like the above into a structure more suitable (in my opinion) as the code.

class Game
  attr_gtk

  def initialize(args)
    # Separate setup method is easier if you need to
    # reset during the game
    setup(args)
  end

  def setup(args)
    # Since static_sprites persists between ticks,
    # need to clear it in case of reset
    args.outputs.static_sprites.clear

    @player = Player.new(x: args.grid.center_x, y: args.grid.center_y, h: 50, w: 50, speed: 2)

    args.outputs.static_sprites << @player
  end

  def tick(args)
    @player.tick(args)
  end
end

class Player
  attr_sprite

  def initialize(x:, y:, h:, w:, speed:)
    @x = x
    @y = y
    @h = h
    @w = w
    @anchor_x = 0.5
    @anchor_y = 0.5
    @speed = speed
  end

  def tick(args)
    angle = self.angle_to(args.inputs.mouse)

    @x += angle.vector_x * @speed
    @y += angle.vector_y * @speed
  end
end

def tick(args)
  $Game ||= Game.new(args)
  $Game.tick(args)
end

One minor note if you actually run this code - the square will be white (default for sprites) instead of black (default for solids).

Smoothly Growing and Shrinking Sprites in DragonRuby

Justin — Thu, 06 Jul 2023 18:15:41 +0000

This post is about DragonRuby, a Ruby implementation for writing games. Check it out!

Starting Off

Let's start simply by rendering a sprite in the middle of the window. For convenience, the program also renders guidelines marking the center of the window (for brevity, not showing this in later code). Also for convenience, this code uses a sprite included with the DragonRuby distribution.



def tick args
  # Double size of the original sprite, in pixels
  width = 80 * 2
  height = 80 * 2

  # Output sprite in middle of the window
  args.outputs.sprites << {
    x: args.grid.center_x, # Horizontal center
    y: args.grid.center_y, # Vertical center
    w: width,
    h: height,
    path: 'sprites/hexagon/red.png',
  }

  # Add grid lines to mark center of window
  args.outputs.lines << {
    x: 0,
    y: args.grid.center_y,
    x2: args.grid.w,
    y2: args.grid.center_y
  } <<
  {
    x: args.grid.center_x,
    y: 0,
    x2: args.grid.center_x,
    y2: args.grid.h
  }
end

As you can see, we've perfectly rendered a sprite in the center of the -

Wait, that's not quite right. What happened?

Anchoring

In DragonRuby, the (0, 0) coordinate is the bottom-left of the window. Similarly, when setting x and y location for a sprite, those correspond to the bottom-left of the sprite.

This could be solved with some math like x = x + (sprite.w / 2) to adjust the sprite appropriately. But this will cause complications later when resizing the sprite.

Preview of the problem:

This might be what you want, but for this post we want the sprite to expand/shrink from the center.

A simpler approach that trying to move x and y around is to instead use the anchor_x and anchor_y attributes.

Important note: anchor_* attributes were introduced in DragonRuby 4.8.

These are very similar to the angle_anchor_* attributes discussed previously.

The values used for the anchors are a percentage of the width or height of the sprite. This diagram from the earlier post might help:

The default "anchors" are essentially at (0, 0) (technically, they are nil, but never mind that).

The center of the sprite is at (0.5, 0.5).

In code:



def tick args
  # Double size of the original sprite
  width = 80 * 2
  height = 80 * 2

  # Actually render sprite in middle of the window
  args.outputs.sprites << {
    x: args.grid.center_x,
    y: args.grid.center_y,
    w: width,
    h: height,
    anchor_x: 0.5,
    anchor_y: 0.5,
    path: 'sprites/hexagon/red.png',
  }
end

There we go! Digression over, back to squishing and stretching this sprite.

"Simple" Approach

For the first approach, let's do this:

Set a rate of growth (e.g. 1 pixel per tick)
Set a target size
Grow (or shrink) the size on each tick
When the target size is met, reverse direction

To avoid some duplication, this code uses the same size for width and height. Adjust as desired.



def tick args
  # How big to make the sprite
  target_size = 80 * 2

  # Current size of the sprite
  args.state.size ||= 0

  # How fast to grow
  args.state.growth_rate ||= 1

  # If the target size is reached, reverse
  if args.state.size >= target_size
    args.state.growth_rate = -1
  elsif args.state.size <= 0
    args.state.growth_rate = 1
  end

  # Grow (or shrink) the size
  args.state.size += args.state.growth_rate

  args.outputs.sprites << {
    x: args.grid.center_x,
    y: args.grid.center_y,
    w: args.state.size,
    h: args.state.size,
    path: 'sprites/hexagon/red.png',
    anchor_x: 0.5,
    anchor_y: 0.5,
  }
end

Result:

Nailed it. Post over..?

Easing In

Instead of calculating the growth rate "by hand," wouldn't it be nice if a function could do that for us? Maybe even have the ability to vary the growth rate over time?

args.easing.ease is here for that very reason.

(This video, linked in the DragonRuby docs, is really good. Plus it also will explain the names of the easing functions used below.)

args.easing.ease will return a "percentage" value (between 0 and 1) which can be multiplied against the target value to get the current value. For the example here, that means it will calculate the current percentage of the size of the the sprite.



def tick args
  target_size = 80 * 2
  duration = 60

  args.state.start_time ||= 0
  args.state.easing_function = :identity

  # Calculate percentage (0 to 1) of progress based
  # on the start time, current time, duration, and easing function
  percentage = args.easing.ease args.state.start_time,
                                args.state.tick_count,
                                duration,                         
                                args.state.easing_function

  # Output the scaled image
  args.outputs.sprites << {
    x: args.grid.center_x,
    y: args.grid.center_y,
    w: target_size * percentage,
    h: target_size * percentage,
    path: 'sprites/hexagon/red.png',
    anchor_x: 0.5,
    anchor_y: 0.5,
  }
end

This code uses the :identity function which is linear - essentially the same as the earlier code that adds a constant "growth rate" on each tick.

Here is the result:

Oops, forgot to shrink it back down!

Easing Out

The code is going to get slightly more complicated now. Instead of passing in a single easing function, the new code uses an array of function names. The array is "splatted" into args.ease.easing.

When the set duration is up, the code adds :flip to the list of functions. Instead of going from 0 to 1, the percentage will now go from 1 to 0.

When that's over, :flip is removed from the list and it starts all over.



def tick args
  target_size = 80 * 2
  duration = 60

  args.state.start_time ||= 0

  # List of easing functions                                                   
  args.state.easing_functions ||= [:identity]                                  

  # Calculate percentage (0 to 1) of progress based                            
  # on the start time, current time, duration, and easing function(s)          
  percentage = args.easing.ease args.state.start_time,                         
                                      args.state.tick_count,                   
                                      duration,                                
                                      *args.state.easing_functions             

  # When we reach the end of the duration, switch direction                    
  if args.state.tick_count == args.state.start_time + duration                 
    # Reset the start time for the easing function
    args.state.start_time = args.state.tick_count                              

    if args.state.easing_functions == [:identity]                              
      args.state.easing_functions = [:identity, :flip]                         
    else                                                                       
      args.state.easing_functions = [:identity]                                
    end                                                                        
  end                                                                          

  # Output the scaled image                                                    
  args.outputs.sprites << {                                                    
    x: args.grid.center_x,                                                     
    y: args.grid.center_y,                                                     
    w: target_size * percentage,                                               
    h: target_size * percentage,                                               
    path: 'sprites/hexagon/red.png',                                           
    anchor_x: 0.5,                                                             
    anchor_y: 0.5,                                                             
  }
end

One way to think of [:identity, :flip] is like this:

:identity is f(x) = x and :identity, :flip is g(x) = 1 - f(x). :flip can be used to "reverse" any function.

More Easing

This may not be very exciting, but keep in mind there are several pre-defined easing functions:

:identity (f(x) = x)
:quad (f(x) = x^2)
:cube (f(x) = x^3)
:quint (f(x) = x^4)
:smooth_start_quad (same as :quad)
:smooth_start_cube (same as :cube)
:smooth_start_quart (same as :quart)
:smooth_start_quint (same as :quint)
:smooth_stop_quad (f(x) = 1 - (1 - x)^2)
:smooth_stop_cube (f(x) = 1 - (1 - x)^3)
:smooth_stop_quart (f(x) = 1 - (1 - x)^4)
:smooth_stop_quint (f(x) = 1 - (1 - x)^5)

Mix and match as you'd like... for example, here's growing with :cube but shrinking with :quint:



def tick args
  target_size = 80 * 2
  duration = 60

  args.state.start_time ||= 0

  # List of easing functions                                                   
  args.state.easing_functions ||= [:cube]                                  

  # Calculate percentage (0 to 1) of progress based                            
  # on the start time, current time, duration, and easing function(s)          
  percentage = args.easing.ease args.state.start_time,                         
                                args.state.tick_count,                   
                                duration,                                
                                *args.state.easing_functions             

  # When we reach the end of the duration, switch direction                    
  if args.state.tick_count == args.state.start_time + duration                 
    args.state.start_time = args.state.tick_count                              

    if args.state.easing_functions == [:cube]                              
      args.state.easing_functions = [:quint, :flip]                         
    else                                                                       
      args.state.easing_functions = [:cube]                                
    end                                                                        
  end                                                                          

  # Output the scaled image                                                    
  args.outputs.sprites << {                                                    
    x: args.grid.center_x,                                                     
    y: args.grid.center_y,                                                     
    w: target_size * percentage,                                               
    h: target_size * percentage,                                               
    path: 'sprites/hexagon/red.png',                                           
    anchor_x: 0.5,                                                             
    anchor_y: 0.5,                                                             
  }
end

Closing Out

This post demonstrates two concepts: changing the anchors for a sprite, and using "easing" to set the size of a sprite.

Easing is a general-purpose concept that can be used for any applications, such as smooth movement.

Keep in mind, you can also:

Change up the anchors
Grow/shrink width and height separately
Change up the target width/height as desired (for example, grow all the way but only shrink back a little)
Combine several easing functions together
Write your own easing functions
???

Have fun!

DragonRuby: Moving in Arbitrary Directions

Justin — Tue, 15 Nov 2022 14:00:00 +0000

In a previous post we looked at rotating rectangles in DragonRuby.

Now let's take that one step further to try turning and moving!

In this post, we'll look at very simple movement of a spaceship.

Setup

First, let's get the state all ready.

The code below puts the sprite of a ship in the middle of the screen.

def tick args
  # Setting up initial state
  args.state.ship.w ||= 50
  args.state.ship.h ||= 50
  args.state.ship.x ||= args.grid.center_x - (args.state.ship.w / 2)
  args.state.ship.y ||= args.grid.center_y - (args.state.ship.h / 2)
  args.state.ship.angle ||= 0
  args.state.ship.speed ||= 0

  # Show the ship
  args.outputs.sprites << {
    x: args.state.ship.x,
    y: args.state.ship.y,
    w: args.state.ship.w,
    h: args.state.ship.h,
    path: 'sprites/ship.png',
    angle: args.state.ship.angle,
  }
end

Not too exciting thus far, but we'll make it better.

Rotation

For rotation, we'll turn the ship 2.5 degrees when the left or right arrow keys are pressed or held down.

def tick args
  # Setting up initial state
  args.state.ship.w ||= 50
  args.state.ship.h ||= 50
  args.state.ship.x ||= args.grid.center_x - (args.state.ship.w / 2)
  args.state.ship.y ||= args.grid.center_y - (args.state.ship.h / 2)
  args.state.ship.angle ||= 0 
  args.state.ship.speed ||= 0 

  # Turn left and right
  if args.inputs.keyboard.right
    args.state.ship.angle += 2.5
  elsif args.inputs.keyboard.left
    args.state.ship.angle -= 2.5
  end

  # Keep angle between 0 and 360
  args.state.ship.angle %= 360

  # Show the ship
  args.outputs.sprites << {
    x: args.state.ship.x,
    y: args.state.ship.y,
    w: args.state.ship.w,
    h: args.state.ship.h,
    path: 'sprites/ship.png',
    angle: args.state.ship.angle,
  }
end

Important to note DragonRuby puts 0 straight to the right or "due east", with increasing angles rotating counter-clockwise.

Acceleration

Still keeping things simple, let's accelerate the ship when the up arrow is held down and decelerate otherwise.

For now we won't worry about what direction the ship is heading.

def tick args
  # Setting up initial state
  args.state.ship.w ||= 50
  args.state.ship.h ||= 50
  args.state.ship.x ||= args.grid.center_x - (args.state.ship.w / 2)
  args.state.ship.y ||= args.grid.center_y - (args.state.ship.h / 2)
  args.state.ship.angle ||= 0
  args.state.ship.speed ||= 0

  # Accelerate with up arrow, otherwise decelerate
  if args.inputs.keyboard.up
    args.state.ship.speed += 0.2
  else
    args.state.ship.speed -= 0.1
  end

  # Keep speed between 0 and 10
  args.state.ship.speed = args.state.ship.speed.clamp(0, 10)

  # Turn left and right
  if args.inputs.keyboard.right
    args.state.ship.angle -= 2.5
  elsif args.inputs.keyboard.left
    args.state.ship.angle += 2.5
  end

  # Keep angle between 0 and 360
  args.state.ship.angle %= 360

  # Go?
  args.state.ship.x += args.state.ship.speed

  # Show the ship
  args.outputs.sprites << {
    x: args.state.ship.x,
    y: args.state.ship.y,
    w: args.state.ship.w,
    h: args.state.ship.h,
    path: 'sprites/ship.png',
    angle: args.state.ship.angle,
  }
end

Moving in Arbitrary Directions

We are almost there!

In the code above, we only update the ship's x position. This is just to make sure we have the acceleration/deceleration working how we'd like.

But what we really want is to go in the direction the ship is pointing!

To do so, we need to update both the x and y position, proportional to the angle and speed... ugh that sounds like we might need some math! Trigonometry even??

Actually, DragonRuby comes to the rescue here! Integer#vector will return a unit vector ([x, y] where x and y are between -1 and 1) corresponding to the angle.

For example:

0.vector # => [1.0, 0.0]

So at an angle of 0 degrees, only the x direction is affected.

But all we really need to know is that angle.vector_x and angle.vector_y will give us the "magnitude" we need to convert speed and angle to x and y distance:

  args.state.ship.x += args.state.ship.speed * args.state.ship.angle.vector_x
  args.state.ship.y += args.state.ship.speed * args.state.ship.angle.vector_y

Putting that into context:

def tick args
  # Setting up initial state
  args.state.ship.w ||= 50
  args.state.ship.h ||= 50
  args.state.ship.x ||= args.grid.center_x - (args.state.ship.w / 2)
  args.state.ship.y ||= args.grid.center_y - (args.state.ship.h / 2)
  args.state.ship.angle ||= 0
  args.state.ship.speed ||= 0

  # Accelerate with up arrow, otherwise decelerate
  if args.inputs.keyboard.up
    args.state.ship.speed += 0.2
  else
    args.state.ship.speed -= 0.1
  end

  # Keep speed between 0 and 10
  args.state.ship.speed = args.state.ship.speed.clamp(0, 10)

  # Turn left and right
  if args.inputs.keyboard.right
    args.state.ship.angle -= 2.5
  elsif args.inputs.keyboard.left
    args.state.ship.angle += 2.5
  end

  # Keep angle between 0 and 360
  args.state.ship.angle %= 360

  # Go in the correct direction!
  args.state.ship.x += args.state.ship.speed * args.state.ship.angle.vector_x
  args.state.ship.y += args.state.ship.speed * args.state.ship.angle.vector_y

  # Show the ship
  args.outputs.sprites << {
    x: args.state.ship.x,
    y: args.state.ship.y,
    w: args.state.ship.w,
    h: args.state.ship.h,
    path: 'sprites/ship.png',
    angle: args.state.ship.angle,
  }
end

Staying Within Bounds

Just to round this out, let's do Astroids-style wrap-around to keep the ship on the screen.

args.grid.right is the width of the screen and args.grid.top can be used for the height.

def tick args
  # Setting up initial state
  args.state.ship.w ||= 50
  args.state.ship.h ||= 50
  args.state.ship.x ||= args.grid.center_x - (args.state.ship.w / 2)
  args.state.ship.y ||= args.grid.center_y - (args.state.ship.h / 2)
  args.state.ship.angle ||= 0
  args.state.ship.speed ||= 0

  # Accelerate with up arrow, otherwise decelerate
  if args.inputs.keyboard.up
    args.state.ship.speed += 0.2
  else
    args.state.ship.speed -= 0.1
  end

  # Keep speed between 0 and 10
  args.state.ship.speed = args.state.ship.speed.clamp(0, 10)

  # Turn left and right
  if args.inputs.keyboard.right
    args.state.ship.angle -= 2.5
  elsif args.inputs.keyboard.left
    args.state.ship.angle += 2.5
  end

  # Keep angle between 0 and 360
  args.state.ship.angle %= 360

  # Go in the right direction!
  args.state.ship.x += args.state.ship.speed * args.state.ship.angle.vector_x
  args.state.ship.y += args.state.ship.speed * args.state.ship.angle.vector_y

  # Wrap around to keep the ship on the screen
  args.state.ship.x %= args.grid.right
  args.state.ship.y %= args.grid.top

  # Show the ship
  args.outputs.sprites << {
    x: args.state.ship.x,
    y: args.state.ship.y,
    w: args.state.ship.w,
    h: args.state.ship.h,
    path: 'sprites/ship.png',
    angle: args.state.ship.angle,
  }
end

Conclusion

And there we go. In less than 50 lines of code and with no complicated math, we can move an object around in arbitrary directions!

DragonRuby: Basic Sprite Animation

Justin — Sun, 26 Jun 2022 18:30:25 +0000

Animating sprites in DragonRuby is fairly simple, but it does require putting a couple ideas together.

First, it's best to have a single image with all frames of the animation together, equally spaced apart. I prefer the frames are arranged horizontally from left-to-right, so that is what we will use here.

Here is an example, borrowed from here:

The first frame can be displayed like this:



def tick args
  height = 195
  width = 192

  args.outputs.sprites << {
    x: args.grid.center_x - (width / 2),
    y: args.grid.center_y - (height / 2),
    h: height,
    w: width,
    source_x: 0,
    source_y: 0,
    source_w: width,
    source_h: height,
    path: 'sprites/walking.png',
  }
end

source_x and source_y set the bottom left corner of a "tile" or basically a slice of the image. (To use the top left instead, set tile_x and tile_y). source_w and source_h set the width and height of the tile. The sprite can be scaled when displayed with w and h.

If the frames are laid out horizontally, then all one needs to do is update the source_x value (typically by the width of the tile) in order to change the frame.

Here is an illustration for a few frames:

We could accomplish this by using the multiplying the width of the tile by the current tick (modulo the number of frames, so it loops):



def tick args
  height = 195
  width = 192
  num_frames = 8

  source_x = width * (args.tick_count % num_frames)

  args.outputs.sprites << {
    x: args.grid.center_x - (width / 2),
    y: args.grid.center_y - (height / 2),
    h: height,
    w: width,
    source_x: source_x,
    source_y: 0,
    source_w: width,
    source_h: height,
    path: 'sprites/walking.png',
  }
end

This works... but it's a bit fast for a walk!

This is where DragonRuby helps out. The frame_index method will do the calculation of the current frame for us.

frame_index accepts these arguments:

count: total number of frames in the animation
hold_for: how many ticks to wait between frames
repeat: whether or not to loop

frame_index can be called on any integer, but typically uses the tick number on which the animation started. Below, the code sets this to 0 (the first tick). This could instead be when an event happens, based on input, or anything else.

Multiplying the width of the tile by the frame index results in the source_x value for the current frame of the animation:



def tick args
  height = 195
  width = 192
  num_frames = 8
  start_tick = 0
  delay = 4

  source_x = width * start_tick.frame_index(count: num_frames, hold_for: delay, repeat: true)

  args.outputs.sprites << {
    x: args.grid.center_x - (width / 2),
    y: args.grid.center_y - (height / 2),
    h: height,
    w: width,
    source_x: source_x,
    source_y: 0,
    source_w: width,
    source_h: height,
    path: 'sprites/walking.png',
  }
end

And that's it!

But With Ruby Classes

Once a game starts to get moderately complex, I like to arrange behavior into classes. It's also convenient to use attr_gtk to avoid passing args around and to save on some typing (e.g. args.outputs becomes just outputs).



class MyGame
  attr_gtk

  def initialize(args)
    @my_sprite = MySprite.new(args.grid.center_x, args.grid.center_y)
    args.outputs.static_sprites << @my_sprite
  end

  def tick
    if inputs.mouse.click
      if @my_sprite.running?
        @my_sprite.stop
      else
        @my_sprite.start(args.state.tick_count)
      end
    end

    @my_sprite.update
  end
end

class MySprite
  attr_sprite

  def initialize x, y
    @x = x
    @y = y

    @w = 192
    @h = 195
    @source_x = 0
    @source_y = 0
    @source_w = @w
    @source_h = @h
    @path = 'sprites/walking.png'

    @running = false
  end

  # Set @running to the current tick number
  # this is so the frame_index can use that as the
  # start of the animation timing.
  def start(tick_count)
    @running = tick_count
  end

  def stop
    @running = false
  end

  def running?
    @running
  end

  # Update source_x based on frame_index
  # if currently running
  def update
    if @running
      @source_x = @source_w * @running.frame_index(count: 8, hold_for: 4, repeat: true)
    end
  end
end

def tick args
  $my_game ||= MyGame.new(args)
  $my_game.args = args
  $my_game.tick
end

This example essentially follows my Object-Oriented Starter approach and moves the logic into a game class and a sprite class.

When the mouse is clicked, the sprite starts moving (using the current tick_count as the starting tick). When the mouse is clicked again, the sprite stops.

Source vs. Tile

To use just a piece of an image (for animations or otherwise), there are two options: source_(x|y|h|w) or tile_(x|y|h|w).

These options are nearly identical, except source_y is bottom left and tile_y is top left.

The source_ options were added in DragonRuby 1.6 and are more consistent with the rest of DragonRuby where the origin is the bottom left. On the other hand, the tile_ options align easier with image editors.

Either option works, depending on what is important to you.

Go!

Now that's really it! Get moving!

DragonRuby: Rotating Rectangles

Justin — Sat, 30 Apr 2022 17:48:07 +0000

In DragonRuby, one of the drawing primitives is a "solid" - a rectangle, actually.

Rectangles are defined by the origin point of the bottom-right corner (x, y) and a size in height/width (h, w).

For example, this code paints a black rectangle in roughly the middle of the screen:

def tick(args)
  args.outputs.solids << {
    x: 490,
    y: 310,
    w: 300,
    h: 100,
  }
end

Rectangles are simple and (presumably) fast. But what if we want to put the rectangle at an angle? Or spin it around?

For sprites, there is an angle attribute. Will that work for rectangles? Unfortunately, no.

We could make a rectangle image and use it in a sprite, but that seems wasteful. I don't know if resizing a sprite is very resource-intensive, but I'm sure it takes more cycles than changing the size of a simple rectangle.

Fortunately, there is a middle way.

From the 2.26 release notes (and yes, this is the only place I could find this functionality formally documented, though it is used in examples):

** [API] Pre-defined ~:pixel~ render target now available.
Before ~(boot|tick)~ are invoked, a white solid with a size of 1280x1280
is added as a render target. You can use this predefined render target to
create solids and get ~args.outputs.sprites~ related capabilities.

In other words, it is possible to create an equivalent rectangle to the above like this:

def tick(args)
  args.outputs.sprites << {
    x: 490,
    y: 310,
    w: 300,
    h: 100,
    r: 0,
    g: 0,
    b: 0,
    path: :pixel,
  }
end

The key piece is path: :pixel and creating a sprite instead of a solid.

As is mentioned above, the :pixel render target is white, so to get exactly the same results as before the color is set to black. If no rgb values were specified, it would be a white rectangle.

Now, can we rotate this rectangle?

Sure!

def tick(args)
  args.outputs.sprites << {
    x: 490,
    y: 310,
    w: 300,
    h: 100,
    r: 0,
    g: 0,
    b: 0,
    path: :pixel,
    angle: 45,
  }
end

(By the way, angles in DragonRuby are in degrees.)

Spinning Round and Round

Here is an example of spinning the rectangle around:

def tick(args)
    args.outputs.sprites << {
      x: 490,
      y: 310,
      w: 300,
      h: 100,
      r: 0,
      g: 0,
      b: 0,
      path: :pixel,
      angle: args.tick_count % 360,
    }
end

This is great and all, but what if you'd rather have it spin around like this?

With some sleuthing, you might find the angle_anchor_x and angle_anchor_y attributes. And you would be forgiven for thinking those refer to points on the coordinate grid. But they do not!

Instead, angle_anchor_x and angle_anchor_y are percentages relative to the sprite itself.

In other words, if both anchors are set to 0.5 (the default), the center of the rotation will be the middle of the sprite (half of the width and half of the height).

0,0 is the bottom-left corner of the sprite, as shown above:

def tick(args)
    args.outputs.sprites << {
      x: 490,
      y: 310,
      w: 300,
      h: 100,
      r: 0,
      g: 0,
      b: 0,
      path: :pixel,
      angle: args.tick_count % 360,
      angle_anchor_x: 0,
      angle_anchor_y: 0,
    }
end

Anchor values between 0 and 1 will be inside the sprite. But values greater than 1 or less than 0 will be outside the sprite.

Here is a little reference:

Happy rectangle rotating!

Automatically Partitioning Cloudflare Logs for Athena

Justin — Fri, 18 Feb 2022 15:50:31 +0000

If you are using Cloudflare, it can be helpful to configure Cloudflare to push request logs to S3. Otherwise, the Cloudflare dashboard provides only a limited view into your data (only 72 hours at a time and sampled data instead of full logs).

Once the Cloudflare request logs are in S3, they can be queried using Athena. This blog post even provides a nice CREATE TABLE command to set up the table in Athena.

However, there is a problem. When performing a query in Athena, it might have to scan all of the logs in S3, even if you try to limit the query. This can be slow and costly, as Athena queries are charged per byte scanned.

The only way to really limit the amount of data scanned is to partition the data.

This post assumes you have already set up Cloudflare to push logs to an S3 bucket, configured a database in Athena to access it, and then realized those logs will grow forever, along with your query times.

(If you just want the "how to" without the exposition, jump down to "Setting Up Partitions for Cloudflare Logs".)

Partitioning

Most commonly, you will want to look at logs from a specific time period, so it makes sense to partition the logs by date.

Most of the partitioning documentation suggests the files (or in this case, S3 objects) include a column=value key pair in the name. The column can then be used as a partition.

Unfortunately, Cloudflare does not allow customizing the format of the file names it produces.

Fortunately, the file names do include date/time information. The logs are grouped by date and time range:

s3://mah_s3_bucket/20210812/20210812T223000Z_20210812T224000Z_9af500e2.log.gz

So all we need to do is grab that date "folder" name and that's our partition! Easy, right?

No, wrong. This is AWS. Nothing is easy.

Use a Recurring Job?

Several of the AWS documentation pages suggest using ALTER TABLE to ADD PARTITIONs.

Something like this:

ALTER TABLE cloudflare_logs ADD
  PARTITION (dt = '2021-08-12') LOCATION 's3://mah_log_bucket/20210812/';

But since the logs will grow every day, we'll need to add new a new partition every 24 hours. It is not possible to "predefine" the partitions.

This requires setting up a recurring job... somewhere... to periodically define the new partitions. So now we have to pull in another AWS service to make S3 and Athena work nicely?! No thanks!

Partition Projection

At the bottom of the page about partitions, there is a paragraph about "partition projection" that sounds promising:

To avoid having to manage partitions, you can use partition projection. Partition projection is an option for highly partitioned tables whose structure is known in advance.

Yes, this is what we want! But how does it work?

Essentially like this:

We must define a column, its type, start and end values, and the interval between those values. Athena will then be able to extrapolate all the possible values.

Then we define a pattern to pull the value out of each S3 object name. This allows Athena to figure out which objects (logs) are associated with which partition value.

For example, the partition 20210812 will be associated with s3://mah_s3_bucket/20210812/20210812T223000Z_20210812T224000Z_9af500e2.log.gz

Once that's all done, we can query based on the partition as if it were a column, like:

SELECT * FROM cloudflare_logs
WHERE log_date >= '20210812'
  AND log_date < '20210901';

Setting Up Partitions for Cloudflare Logs

Here are the steps that must be taken to set up the partitions:

Add the partition "column" when creating the table
Set several properties on the table to define the projection
Set the partition pattern to match against object names
Enable projection

(Actually, 2-4 are all the same: set (totally unvalidated) key-value properties on the table.)

Fortunately, all of this can be accomplished with one giant Athena command:

CREATE EXTERNAL TABLE `YOUR_TABLE_NAME`(
  `botscore` int,
  `botscoresrc` string,
  `cachecachestatus` string,
  `cacheresponsebytes` int,
  `cacheresponsestatus` int,
  `clientasn` int,
  `clientcountry` string,
  `clientdevicetype` string,
  `clientip` string,
  `clientipclass` string,
  `clientrequestbytes` int,
  `clientrequesthost` string,
  `clientrequestmethod` string,
  `clientrequestpath` string,
  `clientrequestprotocol` string,
  `clientrequestreferer` string,
  `clientrequesturi` string,
  `clientrequestuseragent` string,
  `clientsslcipher` string,
  `clientsslprotocol` string,
  `clientsrcport` int,
  `edgecolocode` string,
  `edgecoloid` int,
  `edgeendtimestamp` string,
  `edgepathingop` string,
  `edgepathingsrc` string,
  `edgepathingstatus` string,
  `edgeratelimitaction` string,
  `edgeratelimitid` int,
  `edgerequesthost` string,
  `edgeresponsebytes` int,
  `edgeresponsecontenttype` string,
  `edgeresponsestatus` int,
  `edgeserverip` string,
  `edgestarttimestamp` string,
  `firewallmatchesactions` array<string>,
  `firewallmatchesruleids` array<string>,
  `firewallmatchessources` array<string>,
  `originip` string,
  `originresponsestatus` int,
  `originresponsetime` int,
  `originsslprotocol` string,
  `rayid` string,
  `wafaction` string,
  `wafflags` string,
  `wafmatchedvar` string,
  `wafprofile` string,
  `wafruleid` string,
  `wafrulemessage` string,
  `workersubrequest` boolean,
  `zoneid` bigint)
PARTITIONED BY (
  `YOUR_COLUMN_NAME` string)
ROW FORMAT SERDE
  'org.openx.data.jsonserde.JsonSerDe'
STORED AS INPUTFORMAT
  'org.apache.hadoop.mapred.TextInputFormat'
OUTPUTFORMAT
  'org.apache.hadoop.hive.ql.io.IgnoreKeyTextOutputFormat'
LOCATION
  's3://YOUR_BUCKET_NAME/'
TBLPROPERTIES (
  'projection.enabled'='TRUE',
  'projection.YOUR_COLUMN_NAME.format'='yyyyMMdd',
  'projection.YOUR_COLUMN_NAME.interval'='1',
  'projection.YOUR_COLUMN_NAME.interval.unit'='DAYS',
  'projection.YOUR_COLUMN_NAME.range'='YOUR_START_DATE,NOW',
  'projection.YOUR_COLUMN_NAME.type'='date', 

 'storage.location.template'='s3://YOUR_BUCKET_NAME/${YOUR_COLUMN_NAME}/'
)

These are the pieces related to partitioning:

PARTITIONED BY (
  `YOUR_COLUMN_NAME` string)

This tells Athena to set up a column for the partition.

(The type of the partition column must be string, even though the projection type must be date. Does this make any sense? NO.)

Then the table properties.

Turn on projection:

'projection.enabled'='TRUE'

Set the column type to date:

'projection.YOUR_COLUMN_NAME.type'='date'

This is so Athena knows how to interpolate values.

Define the date format to match:

'projection.YOUR_COLUMN_NAME.format'='yyyyMMdd'

Set the interval for the values to one day:

'projection.YOUR_COLUMN_NAME.interval'='1',
'projection.YOUR_COLUMN_NAME.interval.unit'='DAYS'

Set the range for the values:

'projection.YOUR_COLUMN_NAME.range'='YOUR_START_DATE,NOW'

NOW is a special value so the end of the range will always be the current day.

This sets a template to extract the date string from the object name, using the date template defined above, and setting the value in the column name specified for the projection:

'storage.location.template'='s3://YOUR_BUCKET_NAME/${YOUR_COLUMN_NAME}/'

If you are unfamiliar with Athena, it's good to know that deleting/creating tables is low impact. If the table is already created, it is not a big deal to delete it and start over.

Here are the important bits above that you will need to change:

YOUR_TABLE_NAME is whatever you want to name the table. Something like cloudflare_logs would probably make sense.
YOUR_COLUMN_NAME is whatever you want to name the projection "column". Could be dt like in the AWS docs, or log_date or whatever you want.
YOUR_BUCKET_NAME is the name of the S3 bucket.
YOUR START_DATE is the date of the first log. Something like 20210101.

The table should now indicate it is partitioned:

And the partition should show up as a column:

Using Date Partitions

To test if partitions are working as expected, a quick query like this will work:

SELECT DISTINCT(YOUR_COLUMN_NAME)
FROM "YOUR_TABLE_NAME"
LIMIT 10;

The expected output is several dates for which there are logs.

Once that is confirmed, the partition column can be used like any other column. Since the values is a basic ISO date format, comparison operators can be safely used even though the column is really just a string.

For a single day:

SELECT * FROM YOUR_TABLE
WHERE YOUR_COLUMN_NAME = "20200101";

For an inclusive range:

SELECT * FROM YOUR_TABLE
WHERE YOUR_COLUMN_NAME >= "20200101"
  AND YOUR_COLUMN_NAME <= "20210101";

And now your queries can be faster and cheaper!

Sounds in DragonRuby

Justin — Mon, 31 Jan 2022 18:22:43 +0000

The sound API in DragonRuby is a little tricky because at first it seems similar to the sprite API (e.g. using args.outputs) but it diverges sharply when you want to have some more control.

So let's take a quick look at audio in DragonRuby!

Simple Sound Effects

Want to fire off a single sound effect?

Get a sound file in .wav format and then add it on to args.outputs.sounds:

args.outputs.sounds << 'sounds/my_effect.wav'

The sound will play once. This is great for one-off sound effects.

Sound Formats

DragonRuby supports wav and ogg file formats.

In versions of DragonRuby before 5.0, wav files would be played once by default, while ogg files would loop. This is no longer the case.

For the args.outputs.sounds API, both wav and ogg files will now only be played once.

Adjusting the Volume Knob

Playing a sound effect in DragonRuby is pretty easy. But what if we need to adjust the volume or some other attribute of the audio? Or maybe loop the audio?

You might think, based on how sprites work in DragonRuby, you could do something like this:

# This does not work!
args.outputs.sounds << {
  input: 'sounds/my_music.ogg',
  gain: 0.5,      # Half volume
  looping: true  # Loop the audio
}

But this does not work.

Instead, you need to use an entirely different interface: args.audio.

args.audio is a hash table of sounds.

To add a new sound, assign it with a name:

args.audio[:music] = {
  input: 'sounds/my_music.ogg',
  gain: 0.5,
  looping: true
}

To adjust an attribute of the audio, access it by the same name:

# Turn up the volume
args.audio[:music].gain = 0.75

To pause a sound:

args.audio[:music].paused = true

To completely remove a sound:

args.audio.delete :music

More Music Manipulation

This is the full set of options for audio from the documentation:

args.audio[:my_music] = {
  input: 'sounds/my_music.ogg',
  x: 0.0, y: 0.0, z: 0.0,   # Relative position to the listener, x, y, z from -1.0 to 1.0
  gain: 1.0,                # Volume (0.0 to 1.0)
  pitch: 1.0,               # Pitch of the sound (1.0 = original pitch)
  paused: false,            # Set to true to pause
  looping: false,           # Set to true to loop
}

That's it!

DragonRuby: Render Targets

Justin — Tue, 25 Jan 2022 06:12:00 +0000

Next up in my notes on DragonRuby: render targets!

Weirdly, the documentation on DragonRuby's render targets is limited to example code. Personally, I prefer prose when I am trying to learn... so here we are!

In DragonRuby, a render target is like an infinite canvas you can render as many regular sprites onto as you want, then manipulate the whole thing as if it is one sprite.

This is especially good for things like tiled backgrounds that are built once and do not change.

Let's take an example.

Clouds!

Let's start off very simple and build up.

First, here's all the code to render a single 250x250 pixel image to the screen:

def tick args
  clouds = {
    x: 0,
    y: 0,
    h: 250,
    w: 250,
    path: 'sprites/cloud.png'
  }

  args.outputs.sprites << clouds
end

More Clouds

Cool, but I'd like to fill the whole window with clouds, so I'm going to tile them.

The code below makes a 6x3 grid of the cloud image.

(In DragonRuby, the screen is always 1280x720. Our grid is 1500x750 but I'm not trying to be too precise with the numbers here.)

def tick args
  clouds = []

  6.times do |x|
    3.times do |y|
      clouds << {
        x: x * 250,
        y: y * 250,
        h: 250,
        w: 250,
        path: 'sprites/cloud.png'
      }
    end
  end

  args.outputs.sprites << clouds
end

Ah... blue clouds. Nice.

On every tick, the code builds up an array of 18 sprites (images) and renders it out to the screen.

(There are a number of ways to make this more efficient - check out the previous posts in this series for different ways to "cache" the sprite information.)

Render Targets

But in this post we are talking about render targets - which is a way of rendering a bunch of sprites (or any other renderable thing) just once, and then treating the whole group of sprites as a single sprite. This is faster, simpler, and enables some neat effects.

The code only needs minor changes to switch the cloud grid to using a render target instead:

# Move cloud grid creation into a helper method
def make_clouds(args)
  clouds = []

  6.times do |x|
    3.times do |y|
      clouds << {
        x: x * 250,
        y: y * 250,
        h: 250,
        w: 250,
        path: 'sprites/cloud.png'
      }
    end
  end

  # Similar to `args.outputs`,
  # render targets have `.sprites`, `.solids`, etc.
  # The argument will be used as the path below
  args.render_target(:clouds).sprites << clouds
end

def tick(args)
  # Set up the render target on the first tick
  if args.tick_count == 0
    make_clouds(args)
  end

  # Output a single sprite
  # located at 0,0 and the size of the whole grid
  # created in `make_clouds`
  args.outputs.sprites << {
    x: 0,
    y: 0,
    w: 250 * 6,
    h: 250 * 3,
    path: :clouds # Name of the render target!
  }
end

For convenience, the code above moves the creation of the cloud grid and the render target into a helper method which gets called on the first tick of the game.

args.render_target(:clouds) automatically creates a new render target named :clouds if it does not already exist. Then we can render things to it just as if it were args.outputs.

Interestingly, render targets do not seem to have an innate width or height. In order to avoid unintentional scaling, you will need to "know" how big the render target is. In this case, we know it is a 6x3 grid of 250x250 images, so the size is fairly straightforward. I left the math in to make it clearer.

Finally, we reference the render target similarly to an image file, but pass in the name of the render target as the :path instead of an actual file path.

Static Sprites, Too!

As explored in a different post, we can use static_sprites to "render" the sprite once.

# No changes here
def make_clouds(args)
  clouds = []

  6.times do |x|
    3.times do |y|
      clouds << {
        x: x * 250,
        y: y * 250,
        h: 250,
        w: 250,
        path: 'sprites/cloud.png'
      }
    end
  end

  args.render_target(:clouds).sprites << clouds
end

def tick(args)
  if args.tick_count == 0
    make_clouds(args)

    # Create the clouds sprite once
    # and keep it in `args.state`.
    args.state.clouds = {
      x: 0,
      y: 0,
      w: 250 * 6,
      h: 250 * 3,
      path: :clouds
    }

    # Add the clouds sprite just once
    # as a "static" sprite
    args.outputs.static_sprites << args.state.clouds
  end
end

And now we can move the clouds around just by changing the attributes on the render target.

Adding a little bit of code at the end of tick:

  args.state.clouds.x = (Math.sin(args.tick_count / 20) * 100) - 100

(The calculation and numbers aren't really important here, I just fiddled around until something looked decent.)

Oh hey! Those extra pixels on the sides of the cloud grid actually came in handy.

What Else?

Remember, the entire render target is like one sprite now. That means all the regular sprite attributes (e.g. color, size, blending, flipping, rotation) can be applied to the entire thing at once.

Wait, did you say rotation?

Sure, let's make ourselves dizzy.

  args.state.clouds.angle = (Math.sin(args.tick_count / 120) * 180)

Okay, that's as deep as we'll go on render targets in this post!

DragonRuby: Object-Oriented Starter

Justin — Sat, 15 Jan 2022 22:42:30 +0000

I enjoy playing with the DragonRuby Game Toolkit, but the documentation and many of the examples are very much intended for non-Rubyists. Additionally, as a game engine, it's more data/functionally-oriented than most Rubyists are used to. For example, the main game loop in the tick method needs to be implemented as a top-level method.

This post walks through structuring a game in a way that is a little more familiar to Rubyists.

Caveat! I am new to DragonRuby myself and this is not meant to be the "correct" or "best" or even "great" way to organize your code. It's just a pattern I've started using and it might be useful for you!

(By the way, while DragonRuby is a commercial product, you can often grab a free copy. Keep an eye out for sales!)

Starting Example

First, let's start with some code that isn't using any class definitions at all. Everything happens inside tick:

def tick(args)
  # Set up player object
  args.state.player ||= {
    x: args.grid.w / 2,
    y: args.grid.h / 2,
    w: 20,
    h: 20,
  }

  # Move player based on keyboard input
  if args.inputs.keyboard.left
    args.state.player.x -= 10
  elsif args.inputs.keyboard.right
    args.state.player.x += 10
  elsif args.inputs.keyboard.down
    args.state.player.y -= 10
  elsif args.inputs.keyboard.up
    args.state.player.y += 10
  end

  # Render the "player" as a square to the screen
  args.outputs.solids << args.state.player
end

As a reminder, DragonRuby automatically loads up code from a file called mygame/app/main.rb and then calls tick 60 times per second.

args.state is like an OpenStruct where you can add on whatever attributes you want and store whatever you would like. In this case, we add a hash that we name player.

The code then checks for keyboard input and adjusts the position of the "player". (To keep things very simple, we don't worry about keeping the player on the screen.)

Finally, we render the "player" as a solid square.

This is simple enough and the code isn't too complicated. But, just for fun, let's slowly transform it to be a little more "object-oriented".

Game Object

First, let's create a main "game" object to hold our logic, instead of putting it all in tick.

class MyGame
  # Adds convenience methods for args, gtk, keyboard, etc.
  attr_gtk

  def initialize(args)
    args.state.player = {
      x: args.grid.w / 2,
      y: args.grid.h / 2,
      w: 20,
      h: 20,
    }
  end

  def tick
    if keyboard.left
      state.player.x -= 10
    elsif keyboard.right
      state.player.x += 10
    elsif keyboard.down
      state.player.y -= 10
    elsif keyboard.up
      state.player.y += 10
    end

    outputs.solids << state.player
  end
end

def tick args
  $my_game ||= MyGame.new(args)
  $my_game.args = args
  $my_game.tick
end

Now the tick method only sets up the global $my_game on the first tick, then sets args on each tick and calls the game's tick method.

(Tangent alert! Is it necessary to set args on every tick? Not strictly - you could set self.args = args in initialize and it will work okay. But if you want to use DragonRuby's unit test framework, it may cause problems because each test has a fresh copy of args.)

Using attr_gtk allows the code to be a bit shorter. args, state, keyboard, and more now have convenience methods for them.

Instance Variables Instead of State

args.state is essentially a global variable space. This is a big convenience when a game is all top-level methods - otherwise you would have to figure out where to stash all your game state yourself.

However, it's not required to use it.

The code below uses @player to store the player hash, instead of args.state.

class MyGame
  attr_gtk
  attr_reader :player

  def initialize(args)
    @player = {
      x: args.grid.w / 2,
      y: args.grid.h / 2,
      w: 20,
      h: 20,
    }
  end

  def tick
    if keyboard.left
      player.x -= 10
    elsif keyboard.right
      player.x += 10
    elsif keyboard.down
      player.y -= 10
    elsif keyboard.up
      player.y += 10
    end

    outputs.solids << player
  end
end

def tick args
  $my_game ||= MyGame.new(args)
  $my_game.args = args
  $my_game.tick
end

One thing that has thrown me off with DragonRuby is understanding just how much "regular" Ruby I can use. For the most part, other than how the tick method is used as the main game loop, you can use the Ruby language constructs you are comfortable with.

Splitting Things Up

No big change here, but as a game grows it's easier to split the steps of each game loop into different methods.

class MyGame
  attr_gtk
  attr_reader :player

  def initialize(args)
    @player = {
      x: args.grid.w / 2,
      y: args.grid.h / 2,
      w: 20,
      h: 20,
    }
  end

  def tick
    handle_input
    render
  end

  def handle_input
    if keyboard.left
      player.x -= 10
    elsif keyboard.right
      player.x += 10
    elsif keyboard.down
      player.y -= 10
    elsif keyboard.up
      player.y += 10
    end
  end

  def render
    outputs.solids << player
  end
end

def tick args
  $my_game ||= MyGame.new(args)
  $my_game.args = args
  $my_game.tick
end

Player Class

Final step in this post - let's move the "player" out to a separate class.

In this example, it might not make a lot of sense. But in most games there will be a lot of state and logic you might want to associate with the "player" or any other objects in the game. Having it be its own class helps keep the logic in one place.

class MyGame
  attr_gtk
  attr_reader :player

  def initialize(args)
    @player = Player.new(args.grid.w / 2, args.grid.h / 2)
  end

  def tick
    handle_input
    render
  end

  def handle_input
    if keyboard.left
      player.x -= 10
    elsif keyboard.right
      player.x += 10
    elsif keyboard.down
      player.y -= 10
    elsif keyboard.up
      player.y += 10
    end
  end

  def render
    outputs.solids << player
  end
end

class Player
  attr_sprite

  def initialize(x, y)
    @x = x
    @y = y
    @w = 20
    @h = 20
  end
end

def tick args
  $my_game ||= MyGame.new(args)
  $my_game.args = args
  $my_game.tick
end

Here the code uses another DragonRuby convenience. attr_sprite adds a bunch of helper methods that allow you to use any object as a sprite/solid/border, etc. (Note that the code still passes player into outputs.solids and DragonRuby treats it as a solid. If it were passed into outputs.sprites then it would be treated like a sprite instead!)

Separate Files?

For the sake of a blog post, all the code is together. But there is no reason not to start splitting the code across separate files.

But! In DragonRuby there is one weirdness with require: you must include the file extension (usually .rb), while in regular Ruby that is usually omitted.

Wrapping Up

Did our code become longer and less straight-forward? Yes, for this small example, definitely.

But as a game (or any project) grows, pulling bits out into modular pieces is going to be an advantage. Personally I fall back on this structure pretty quickly when I start a new DragonRuby project.

Hopefully this post is useful to Rubyists trying to get into DragonRuby!