Godot Engine GameDev: GameShell Edition [Tutorial]

Run Godot games on the GameShell!

Hi everyone!
In the last weeks I investigated a bit on how to compile the Godot Engine and run Godot games on the GameShell. This is a tutorial on how to do the same on your machine!

Godot is a very powerful free and open source 2D and 3D game engine, although we’re sticking only with 2D on the GameShell!

The entire Godot documentation is at your disposal if you want to learn how to use the engine in general. The “About” and “Step by step” sections are the recommended ones to begin with!

Here we’ll focus on GameShell-specific Godot tips and tricks to get you started!



  1. A GameShell with Clockwork OS v0.5 installed.
  2. Another PC to develop the game on.
  3. The Godot Engine 3.2.3 standard editor binaries.
  4. A 2D game developed with Godot, or a new one you’re about to make!
  5. GameShell Godot export templates, download them here!


Your Godot game will probably not work out of the box on the GameShell, a few tweaks are usually needed. So let’s see what are the guidelines and the changes needed to have your game up and running!

1. Create a new export preset

  • Go to Project -> Export... and add a new Linux/X11 preset, you can call it GameShell or however you like.
    Disable the 64 Bits option and fill the custom template fields with the contents of the templates zip file you downloaded. godot.x11.debug.32 is the debug build and godot.x11.opt.32 is the release one.

  • If you plan to release the game on other platforms besides the GameShell, it is a good idea to create a custom feature for it in the Features tab.

  • 68747470733a2f2f692e696d6775722e636f6d2f637754485564362e706e67

  • 68747470733a2f2f692e696d6775722e636f6d2f6d36307433307a2e706e67

2. Change your project settings

  • You can override values for the GameShell only if you select the label of a property and click on Override For... in the top right corner of the popup window, then select the feature you created earlier. A new property named <property_name>.<feature_name> will appear, this is the property you’ll have to change.

  • Project Settings -> Display -> Window: set the window width and height to 320x240. This is the GameShell screen resolution.
    Set the aspect and the mode too. keep_width and 2d usually work best, but it may depend on the game you’re making.

  • Project Settings -> Rendering -> Quality: the GameShell supports GLES2 only. Change the driver name.
    It’s recommended to change the framebuffer allocation to 2D Without Sampling , but you can try setting it to 2D if you need.

3. Map the MENU button

  • One of the GameShell conventions is that when you press the MENU button, you exit the app or game you’re currently in.

  • The MENU button is mapped to the escape key, so just create a new action ui_escape in the Input Map settings that activates with the escape key and add this snippet somewhere in your code, where it is always running:

    if OS.has_feature("GameShell") and Input.is_action_pressed("ui_escape"):
  • Remove the feature check if you didn’t create one.

4. The other inputs need to be remapped

  • This is the GameShell keypad mapping:

  • One way you can do it is by adding a similar piece of code inside a function that is called on startup:
    if OS.has_feature("GameShell"):
        InputMap.action_erase_events("ui_accept")   # Erase the previous mapping.
        var ev =                # Create a new event that will activate the action.
        ev.pressed = true                           # Action activates on key pressed.
        ev.scancode = KEY_K                         # The key to press is K, which is the B button.
        InputMap.action_add_event("ui_accept", ev)  # Add the action back into the InputMap.
        ... # Repeat for each action you want to remap.

5. Export your project

  • Go into Project -> Export..., select the GameShell preset and click on Export Project , make sure to disable the Export With Debug option.

6. Add the game into your GameShell

  • There are a few ways you can do this. The simpler one is to connect to your GameShell’s file system through network share, the needed ips are listed in Tiny Cloud under “For Windows network”.

  • Your OS should be capable of mapping a network drive using those ips. Choose the one for games (~/games/ ). Add your game (executable + .pck files) inside a new GameName folder.
    Alternatively you can transfer your files with SCP using the command line.

  • The game needs to have execute permission, SSH into your GameShell:

    cd ~/games/GameName/
    sudo chmod +x *
  • From the GameShell, you can then open the Bean file browser, navigate to /home/cpi/games/GameName , highlight the game executable, press MENU and choose Execute. That’s it!

7. Add a launcher entry

  • It is generally preferable to have a shortcut to your game directly in the launcher. To do that, SSH into your GameShell and create a new script file inside the ~/apps/Menu/GameShell directory.

    cd ~/apps/Menu/GameShell
  • The contents of this file should be:

  • Add execute permission:

    sudo chmod +x
  • The GameShell launcher uses the directory structure and the executable scripts inside ~/apps/Menu/GameShell to generate its entries each time the launcher is reloaded, so feel free to add your entries wherever you like.

  • Reload the UI or reboot your GameShell and you should be good to go!

8. Set a custom icon for your launcher entry.

  • To assign a custom icon to your game, by default you’ll have to add a new image file in the directory structure under ~/launcher/skin/default/Menu/GameShell , in the same location and using the same name of the script you created earlier.

  • In case you changed your default launcher, the same procedure should apply changing the base directory to the appropriate one.

That should be it!

Here’s one of my games, Gumgem, running on the GameShell!

More info and instruction to compile Godot yourself are available here on my repository:

Have fun developing games for the GameShell!


Thanks for the wonderful tutorial and templates! We need more of these. Great contribution to the community. :+1:


Thanks! I’ve been wanting to try godot for some time, and now there’s one more reason to do it :slight_smile:

1 Like

That’s great! Let me know if you have difficulties during the procedure above, I’ll try to fix and make things clearer if that happens!

1 Like

Hey, this is a really cool project! I’ve been working with Godot for a bit and this seems like the perfect way to do stuff for the Gameshell, so kudos for putting this together! However, I’ve been running into a bit of a problem over the past few days of trying to get it to work.

I can get the .x86 and .pck files onto the Gameshell fine, and make it executable, but whenever I go to run it, it always crashes after the boot screen. There’s not much to the project I’m exporting, just a blank screen with “If you see this, it works, reboot the Gameshell to quit.” No scripts or anything, so I’m a bit at a loss as to what could be causing the issue.

I’m certain it has to be something on my end, since the tutorial you wrote out was easy enough to be followed by anyone, but I’ve double checked between the setup instructions you gave and what I’ve put together and I can’t find anything different: Latest Clockwork OS, Godot 3.2.3, the export templates, 32-bit export, etc. all look the same on my end. I’m very bad at looking for things, though, so again it’s almost certainly just me.

Anyway, I’ll keep plugging away at it and hopefully I can find the issue on my end. IF so, I’ll update back here in case anyone else is having this issue!

1 Like

It’s unfortunate that your test project doesn’t work for now, but thanks!
So, alright, can you post here or dm me the project you’re trying to run? I’ll check it too to see what’s wrong.