Godot Engine GameDev: GameShell Edition [Tutorial]

[Samdze]

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!

Requirements

NOTICE: there seems to be issues and crashes with the 512 MB of ram version of the GameShell using the lima driver.
Fbturbo seems to work fine even if with lower performance.
Feel free to try the procedure on a 512 MB GameShell and let me know how it goes in DM.

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!
   
   

Setup

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.

• 

• 

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"):
      get_tree().quit()
  

• 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 = InputEventKey.new()                # 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 directory.

  cd ~/apps/Menu
  nano GameName.sh
  

• The contents of this file should be:

  #!/bin/bash
  ~/games/GameName/ExecutableName
  

• Important, add execute permission, the launcher may not be able to boot correctly otherwise:

  sudo chmod +x GameName.sh
  

• The GameShell launcher uses the directory structure and the executable scripts inside ~/apps/Menu 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:

samdze/godot-gameshell

Have fun developing games for the GameShell!

Post your Godot projects and screenshots here in this topic!

[yong]

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

[edward]

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

[Samdze]

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!

[Spoolicus]

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!

[Samdze]

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.

[Orestiskon]

Hi,
thanks a lot for the tutorial. I followed every step up until making a shortcut in the menu.
Unfortunately, when I tried to run it, gameshell crashed, and since then it doesn’t boot at all. Any ideas on how to restore it and perhaps run the game?

I used my entry for the Global Game Jam as a test, you can find it here:

Recollect.zip

There is a folder in the project “for Gameshell” with the export already done.

Edit: It seems the boot problem was due to battery, it seems to have emptied suddenly so it might be that it was running out while booting. But the game still refuses to launch.

[Samdze]

Hi Orestiskon, I tried your project, I just exported it as is using the Gameshell export template, and it works perfectly on my freshly installed Clockwork OS v0.5 (lima drivers enabled).
For this test I just launched the game from the Bean app.

Screenshot

Yours seems like an issue with the stock launcher, I recall it refuses to boot correctly if a script you placed in the ~/apps/Menu subfolders has not execute permissions.
You can ssh into the GameShell even if it doesn’t boot into the stock launcher, then check the execute flag of your scripts.

[Orestiskon]

Hi Samdze,
awesome to see it running in the Gameshell! However I tried on the Bean too using lima drivers and it still couldn’t load it.

I’m pretty newbie with Linux, one thing that might differ from the tutorial is the directory I copied the game. I used the Games folder shown in Tinycloud, while “~games” seems to point at /usr/games.

In any case, I went to the game’s folder, run “sudo chmod +x *” but the game still won’t run. Any ideas?

[Samdze]

The command you should run to fix the booting issue is:

@Samdze

sudo chmod +x GameName.sh

inside the script folder. ("~/apps/Menu/…", not the folder containing the game)

When “~/” is written it is assumed that it’s the"/home/cpi/" folder.
Be careful because when you write ~ using sudo it refers to the root directory “/” instead of “/home/cpi”.
Unfortunately this part is a little fragile if you’re unfamiliar with linux.

What do you get when trying to run the game? Does the Godot splash screen appear? Or you just get nothing?

[Orestiskon]

For now I’m not trying to use the shortcut, I just try to run it with Bean.
I don’t get the Godot logo at all, it’s just black screen for a couple of seconds and then it goes back to Bean.

[Samdze]

Do you have the Game.x86 and Game.pck in the same folder, each with the same filename? (except for the file extension)
If you’re sure the executable has execute permissions, it should work.
Your splash screen is transparent, so a black screen probably means the engine is trying to load the pck file.

If the game crashes when trying to load the pck, a log file would be useful.
You should be able to find log files inside the
/home/cpi/.local/share/godot/app_userdata/GameName/logs/
folder.
If nothing useful has been printed, you can try running the game using the debug version of the engine to see if it outputs more info.

[Orestiskon]

Thanks for the reply,
I’m trying to see if there’s any useful information, unfortunately the logs only seem to state the engine version.

I tried re-copying the files and giving them permissions again but still didn’t work.
How do you mean using the debug version?
I guess another thing I could try is to make a fresh OS install.

[Samdze]

@Orestiskon

How do you mean using the debug version?

Export using the debug export template, it is around 153 MB compared to ~21 MB of the release template.

It is better if you DM me at this point, I’ll update this topic if something useful is discovered.

[Orestiskon]

Thanks a lot for trying to help. I can’t seem to find how to send DMs here, so I’ve sent you a message on twitter. Cheers.

[Petrakis]

That’s because of trust level, I added trust level 1 to you so you can send DM’s.

[Samdze]

The issues seem to be attributable to the 512 MB of ram version of the GameShell.
I’m not able to test this in depth as I only have the clockworkPi v3.1 board, for now I’ll add a notice stating that only the 1 GB version is supported.

I’ll investigate further in the coming days.

UPDATE: it seems that disabling the lima driver the engine works fine even on the 512 MB version of the GameShell. There may still be bugs in the lima driver implementation.

[edward]

hey!
first of all I’d like to thank you for writing this tutorial. it inspired me to finally try making my first game.
I followed it in the middle of development of my game and it worked perfectly right from the first try. But unfortunately when I finished my first prototype, I was not able to run it on GS, and I can’t figure out why. I’ve tried following the instructions to redo everything from scratch, I’ve tried switching driver on GS (I have 1gb version, so I assume it’s not the case here), and nomatter what I do I just get black screen when I run the game, and then get back to the menu. Might it be something in the code or project settings that messed everything up? any idea where to start debugging this?

[Samdze]

Thanks for your words! It makes me very happy to read that it inspired you to begin your gamedev journey!

Regarding the issue you’re having, you might be using a feature or a part of the engine that’s not supported, one way to investigate is by looking at the log files the engine generates when it runs, here:
/home/cpi/.local/share/godot/app_userdata/GameName/logs/

If nothing useful is shown you may try executing the game using the debug template instead of the release one.
To generate log files in a directory of your choosing, you can also write something like this in your executable bash script:

#!/bin/bash
~/games/GameName/ExecutableName > ~/game.log 2>&1

This will generate a game.log file inside your cpi home directory.
If you still have no clue what’s wrong, you can DM me and I’ll try to help!

[edward]

Thanks. I didn’t take a look at the logs yet, but I’ve been able to run the game. For some reason when I use “Export All” it works right away, but if I export only gameshell template then I face the problem I described. This sounds weird, but at least it works now. I’ll take a look at the logs later