Home Creators Posts Import Register Favorites Logout
haven't archived this post yet. have a subscription? use the importer!

Downloads

  • 121820 Shield Cat - Windows.zip
  • 121820 Shield Cat - Linux ARM.zip
  • 121820 Shield Cat - Linux x86_64.zip
  • 090620 Shield Cat SAGE Demo - Windows.zip
  • 090620 Shield Cat SAGE Demo - Linux.zip
  • 121920 Shield Cat - Android.apk

Missing 2 full-res photos, 6 files, as this post has not yet been imported.

Content

Please note, this is an article about the technical aspects of getting a Gamemaker Studio 2.3 game to run on Raspberry Pi from a developer's perspective. It is not intended for people who simply wish to run the game.

Attached at the end of this post are development builds of Shield Cat, including a Raspberry Pi build that you can try out. The SAGE demo is also included, but this version lacks a Raspberry Pi build. If you simply want to try out the game, scroll to the bottom.

Building for ARM Linux

Before you begin, you'll need Gamemaker Studio 2.3.1, which allows for export to the ARM Linux target. You'll also need an ARM Linux device to build with (the Raspberry Pi.)

The initial work of setting up for building on the Pi is outside the scope of this article, but you can find detailed steps at this link below:

https://meseta.medium.com/setting-up-gamemaker-builds-on-the-rpi-81ecab7e0638

The Initial Build

The thing about the Raspberry Pi is that it is, of course, a small single board computer. Therefore, you're not going to get amazing results out of it, and you're going to run into many limitations. For instance, when I first ran Shield Cat on there, the game ran at less than 1fps!

This article does not contain some sort of hidden trick or magic bullet to make games run well on the Pi. Even with all the optimizations, Shield Cat still can only run at 60fps at 1280x720 or below. However, I'm hoping that sharing some of the optimization techniques I use will help other people to run their own Gamemaker projects on the platform.

Shield Cat's Rendering Pipeline

Before I get into the Pi-specific optimizations I've made, I feel I need to discuss the optimizations I already had in place. For this, I need to talk about exactly how Shield Cat gets the picture to the screen.

Alpha Blending (or lack thereof)

The first thing is alpha blending. As a pixel art game, Shield Cat uses absolutely no alpha blending. What this means is that, any graphic that relies on image_alpha will not be transparent. The following 3 functions help with this:

  • gpu_set_colorwriteenable(true, true, true, false) – Allows writing red, green, and blue values when drawing sprites, but does not write alpha values.
  • gpu_set_alphatestenable(true) – Enables alpha testing. What this does is, it considers all pixels on a threshold between 0 and 128. Any pixels above the threshold get drawn at full opacity, and any pixels below the threshold get discarded. Otherwise stated, the more transparent a pixel is, the most likely it is to simply be thrown away and not drawn.
  • gpu_set_alphatestref(64) – Sets the threshold by which the alpha will be tested. Otherwise stated, any pixel that's more than halfway transparent will be drawn (but with no transparency) and any pixel that's less than halfway transparent will be thrown away and not drawn.

The combination of these functions allow the game to draw a lot faster. Even on modern GPUs, alpha transparency can slow down games considerably, especially when several semitransparent graphics are stacked on top of each other. Even if a sprite has completely transparent parts, math is still done on them. With these settings, we can forego all of this extra math.

The way Shield Cat works around this is by using blend modes. Color math from blending is a lot faster and easier for the GPU to process, and still allows for many effects – including faking transparency. The game uses an overlay to enhance the look of scenes, but this is drawn using gpu_set_blendmode_ext(bm_dest_color, bm_src_color)

This scene uses a sprite overlay. The game uses draw_sprite_general to sample a very small part of the sprite and then stretch it over the game view using texture filtering.

Instance Optimization

In order to optimize CPU and GPU usage, Shield Cat splits the room into different “areas.” When Lance steps into one of these areas, all objects in the area are activated, and all objects outside of the area are deactivated. Instance management is outside the scope of this post, but basically any object that is deactivated will not exist in the room and simply will reside in memory. This can help speed up the game considerably, especially if there are a lot of instances in the room.

Screen Resolution

Note: this section assumes you are familiar with Gamemaker Surfaces and using Room Views. In short, a Surface is a texture that you can render the game to, and Views are a way to specify where the game will appear on the screen.

When drawing the game, Shield Cat does not use the application surface. Instead, the application surface is disabled, and I use a custom surface. This surface's resolution is 640x360, and allows the game to draw much faster as it's not stretching all the sprites to fit the screen's actual resolution. I use the function view_set_surface_id in the Pre-Draw event to make sure that the game draws the view to the surface I specify.

I should point out now, rendering to a surface can be slow, and if you disable using all surfaces, you can draw directly to the back buffer. However, this has its own host of issues: You'll lose access to any depth sorting, so sprites may be drawn in the wrong order, and the game is drawn at the screen's resolution. Especially in the case of the Raspberry Pi, it is actually faster to draw to the texture and then upscale it than it is to draw directly to the back buffer, as the game instead has to stretch all the sprites individually to fit the screen.

Drawing the Surfaces

Shield Cat has a bit of an unorthodox method of drawing: the game actually uses two surfaces to draw. In the Post-Draw event, the game switches to another surface which is sized to the screen resolution. For example, if the game is running at 1920x1080, the game is first drawn to the surface at 640x360, and then drawing is swapped to another surface that is 1920x1080. Finally, the 640x360 is drawn onto this new surface by upscaling it. A shader is used when upscaling it to apply some optional visual effects, but that is outside the scope of this post.

An illustration of the two surfaces and how they're rendered, not to exact scale.

After the game is drawn to the larger surface, the Gradient Overlay and UI elements such as Lance's health are drawn to the screen. If they were drawn beforehand, they would also be affected by any of the optional visual effects.

I have not brought this up yet, but texture filtering is disabled during all of this. The reason is that, since the game is a pixel art game, any texture filtering can smooth out the graphics and make it look blurry. The upscaled surface is always an exact multiple of the base resolution (2x upscale at 1280x720, 3x upscale at 1920x1080, etc.) so texture interpolation is not necessary and will only blur the result anyways.

After we have our larger surface, we can draw it in the Draw GUI event. The game has three upscaling methods you can choose from:

  • Integer Upscaling: The game will always upscale at an exact multiple and will not fill the screen. For example, if your screen is 1680x1050, the game will draw at 1280x720, and a black border will be present around the entire screen.
  • Fractional Fast: The game will upscale a low resolution surface to fill the screen. For example, on the 1680x1050 screen, the game will first upscale to 1280x720, and then stretch it in the Draw GUI event to fill the screen.
  • Fractional HQ: The game will downscale a high resolution surface to fit in the screen. On our 1680x1050 screen, the game will upscale to 1920x1080, and then downscale that to fit our display. Please note that this can be incredibly slow on older and low end hardware, as devices tend not to like surfaces that are bigger than the screen resolution.

I should mention that Shield Cat also has an optional hi-res rendering mode. Instead of drawing the game at 640x360 on a 1920x1080 display and then upscaling, it will always draw at 1920x1080. The result is nice, but also it takes longer to draw.

Drawing to the Pi

Now that you know the general process by which Shield Cat gets a picture to the screen, it's time to discuss the changes necessary to get it to run on the Raspberry Pi and run well.

Shield Cat has exactly one option in its INI file which helps tremendously, which I named InternalUpscale. When disabled, the following is done:

  • The game's second surface will no longer be upscaled. Both surfaces will be 640x360, meaning that the game only has to upscale to fit the screen one time (in the Draw GUI event.) You might think that it would be faster to simply use one surface, but as discussed earlier if I were to do it this way then any UI elements like Lance's health and whatnot would be affected by any color blending.
  • When the game's second surface is upscaled, it will only use Integer Upscaling. The reason is that, since both surfaces are now 640x360, the game must be drawn and upscaled without texture filtering (or it will be blurry.) Also, an exact integer upscale is a lot faster. I tried making it fill the screen anyways by using an odd resolution, but it slowed down terribly.
  • All optional post processing effects are disabled. Usually when drawing the upscaled surface, the game uses a shader to add optional effects. Here, however, the game simply doesn't even set the shader at all and draws using the default shader.

Setting The Pi Itself

Note: I only have a Pi 3B+, so I can't guarantee what is discussed here will work on older versions of the Pi. Also, I am using Raspberry Pi OS, and instructions for other Linux distributions are outside the scope of this post.

In order to get the Pi to run games at a good framerate, you'll have to make a few changes using raspi-config. Specific instructions are outside the scope of this post, but the information is pretty easy to find.

  • GPU Memory Allocation – You may need to allocate more memory to be used by the GPU. Allocating too much can cause negative performance on the Pi. My Pi has 1GB of RAM, so I set 256MB to be used by the GPU. I can probably go for less, but I wanted to be sure. (Note: as I understand it, the Pi 4 dynamically allocates RAM to the GPU, so you can skip this step.)
  • Enabling OpenGL Drivers – In order to get OpenGL programs to run on the Pi, you need to enable the OpenGL drivers. In the advanced options, there's an option for GL Drivers. I set it to “GL (Full KMS) Desktop Drivers.”
  • Disabling Desktop Compositing – Make sure that desktop compositing is disabled, as having it enabled can slow down the game considerably.

It is important to note that these settings can have an impact on general desktop usage of the Pi, but they sure make Shield Cat run a lot faster, and that's the goal here.

How To Apply This To Your Game

Every Gamemaker game is different, and so the solution I used may not work for you. For instance, many games simply use the Application Surface. I find that it stretches to the size of the display though, causing the aforementioned issue of upscaling all sprites drawn individually. Also, if your game relies on a lot of alpha blending or complex shaders, you may need to make serious changes in order to get the game to run on the Pi.

The important thing is to know that there are many limitations when trying to get the game to run on the Pi, and it's going to be a lot of work. Additionally, it may even be impossible to do it, depending on how complex your game's graphics or code are. The purpose of this post is to simply offer insight on how my game works, and how I got it to run on the Raspberry Pi.

Remember, even with all the optimizations I've done, I can still only get the game to run at 1280x720 (even on the Pi 4.) I believe this is simply due to the GPU not having enough memory bandwidth to upscale the game's image to 1920x1080. (Note: Memory bandwidth is also why upscaling sprites individually can be so slow.) I even tried it with a blank project with some test images and code, but I couldn't get it to go that well.

A random note, but if your game uses Retro Palette Swapper by Pixelated Pope, it is impossible to run it on the Raspberry Pi. This is because Retro Palette Swapper requires Shader Model 3, which the Raspberry Pi does not support.

Going Forward

Exporting to the Raspberry Pi is still a relatively new feature of Gamemaker, so we are still in the early days of what can be done. In the future, there may be better hardware/software support to help make the process easier, but I'm hoping that more people are able to get together on this. The Pi is already seen as a great emulation device for playing retro games, but it would be very nice to see it as a general gaming machine for new and original indie games.

I hope that what I've written here gives you some insight on the challenges of running a game not optimized for the Pi on there, and hopefully more people will be encouraged to at least give it a go. It's difficult, but rewarding. Remember, my game initially ran at less than 1 frame per second, and can now achieve 60fps. (Interesting to note: my game gets about 35fps when run at 1920x1080. If your game targets 30fps, it may just be possible to get it going on there just fine.)

Trying It Out

The best way to see how it works is to see it in person, I feel. Therefore, I've attached Shield Cat's developmental builds to this post.

Important Things To Know:

  • If you played the SAGE 2020 demo, this is not that! If you want a fully featured demo of Shield Cat, download the files named 090620 Shield Cat SAGE Demo.
  • This is a development build of Shield Cat as I rewrite the code from the ground up. Therefore, many features are missing from the development builds. This build does not have any in-game menus, you can't talk to anyone or read any signs, and the map is unfinished. Additionally, Lance's Shield doesn't work on enemies, there's no music, and Gamepad support is limited.
  • The development builds are named "121820 Shield Cat"
  • In order to get the game to run on the Pi, you'll need the Linux ARM build, and you'll need to follow the instructions found in assets/install_and_config.txt under Raspberry Pi. Instructions on how to modify config/main.ini are also included. Please read these instructions before asking questions.
  • Windows and Desktop versions of Linux are included so you can compare the changes between these versions and the Raspberry Pi version.
  • The games use the same save data folder, but use different files. The SAGE demo of Shield Cat uses /config.ini, while the new one uses /config/main.ini. Please keep in mind the distinction when running these games.
  • I also attached the experimental Android build of the game, if you want to play around with that. Tapping and moving your finger on the left side of the screen moves Lance, while the right side allows you to spin and throw your shield.

Remember, the builds presented below are incomplete builds from me rewriting the game's base code, and many features are missing. Do not expect a fully featured demo! These are simply in-development builds that are normally available only to Patrons.

If you want a demo of what Shield Cat is really like, download the "Shield Cat SAGE Demo" files!

Talk To Me

If you want to talk to me about this post, Shield Cat, the Raspberry Pi, Linux in general, or your favorite Final Fantasy game, please feel free to join our discord! We have a lovely community and would love to talk to you. Thank you!

https://discord.gg/NdYQXJUwRd 

Files

Previews only

Comments

No comments found for this post.