Planet SurreyLUG

Syndicate content
Updated: 1 hour 8 min ago

Easily port mobile HTML5 games to Ubuntu Phone

Tue, 28/07/2015 - 13:36

Article also available in Spanish at http://thinkonbytes.blogspot.co.uk/2015/07/migrar-facilmente-juegos-moviles-en.html thanks to Marcos Costales.

I really like playing games on my phone & tablet and wanted some more games to play on Ubuntu. With a little work it turns out it’s really pretty easy to ‘port’ games over to Ubuntu phone. I put the word ‘port’ in quotes simply because in some cases it’s not a tremendous amount of effort, so calling it a ‘port’ might make people think it’s more work than it is.

Update: A few people have asked why someone would want to even do this, and why not just bookmark a game in the browser. Sorry if that’s not clear. With this method the game is entirely cached offline on the customer phone. Having fully offline games is desirable in many situations including when travelling or in a location with spotty Internet access. Not all games are fully offline of course, this method wouldn’t help with a large on-line multi-player game like Clash of Clans for example. It would be great for many other titles though. This method also makes use of application confinement on Ubuntu so the app/game cannot access anything outside of the game data directory.

I worked with sturmflut from the Ubuntu Insiders on this over a few evenings and weekends. He wrote it up in his post Panda Madness.

We had some fun porting a few games and I wanted to share what we did so others can do the same. We created a simple template on github which can be used as a starting point, but I wanted to explain the process and the issues I had, so others can port apps/games.

If you have any questions feel free to leave me a comment, or if you’d rather talk privately you can get in contact in other ways.

Proof of concept

To prove that we could easily port existing games, we licensed a couple of games from Code Canyon. This is a marketplace where developers can license their games either for other developers to learn from, build upon or redistribute as-is. I started with a little game called Don’t Crash which is an HTML5 game written using Construct 2. I could have licensed other games, and other marketplaces are also available, but this seemed like a good low-cost way for me to test out this process.

Side note: Construct 2 by Scirra is a popular, powerful, point-and-click Windows-only tool for developing cross-platform HTML5 apps and games. It’s used by a lot of indie game developers to create games for desktop browsers and mobile devices alike. In development is Construct 3 which aims to be backwards compatible, and available on Linux too.

Before I licensed Don’t Crash I checked it worked satisfactorily on Ubuntu phone using the live preview feature on Code Canyon. I was happy it worked, so I paid and received a download containing the ‘source’ Construct 2 files.

If you’re a developer with your own game, then you can of course skip the above step, because you’ve already got the code to port.

Porting to Ubuntu

The absolute minimum needed to port a game is a few text files and the directory containing the game code. Sometimes a couple of tweaks are needed for things like permissions and lock rotation, but mostly it Just Works(TM).

I’m using an Ubuntu machine for all the packaging and testing, but in this instance I needed a Windows machine to export out the game runtime using Construct 2. Your requirements may vary, but for Ubuntu if you don’t have one, you could install it in a VM like VMWare or VirtualBox, then add the SDK tools as detailed at developer.ubuntu.com.

This is the entire contents of the directory, with the game itself in the www/ folder.

alan@deep-thought:~/phablet/code/popey/licensed/html5_dontcrash⟫ ls -l total 52 -rw-rw-r-- 1 alan alan 171 Jul 25 00:51 app.desktop -rw-rw-r-- 1 alan alan 167 Jun 9 17:19 app.json -rw-rw-r-- 1 alan alan 32826 May 19 19:01 icon.png -rw-rw-r-- 1 alan alan 366 Jul 25 00:51 manifest.json drwxrwxr-x 4 alan alan 4096 Jul 24 23:55 www Creating the metadata Manifest

This contains the basic details about your app like name, description, author, contact email and so on. Here’s mine (called manifest.json) from the latest version of Don’t Crash. Most of it should be fairly self-explanitory. You can simply replace each of the fields with your app details.

{ "description": "Don't Crash!", "framework": "ubuntu-sdk-14.10-html", "hooks": { "dontcrash": { "apparmor": "app.json", "desktop": "app.desktop" } }, "maintainer": "Alan Pope ", "name": "dontcrash.popey", "title": "Don't Crash!", "version": "0.22" }

Note: “popey” is my developer namespace in the store, you’ll need to specify your namespace which you configure in your account page on the developer portal.

Security profile

Named app.json, this details what permissions my app needs in order to run:-

{ "template": "ubuntu-webapp", "policy_groups": [ "networking", "audio", "video", "webview" ], "policy_version": 1.2 } Desktop file

This defines how the app is launched, what the icon filename is, and some other details:-

[Desktop Entry] Name=Don't Crash Comment=Avoid the other cars Exec=webapp-container $@ www/index.html Terminal=false Type=Application X-Ubuntu-Touch=true Icon=./icon.png

Again, change the Name and Comment fields, and you’re mostly done here.

Building a click package

With those files created, and an icon.png thrown in, I can now build my click package for uploading to the store. Here’s that process in its entirety:-

alan@deep-thought:~/phablet/code/popey/licensed⟫ click build html5_dontcrash/ Now executing: click-review ./dontcrash.popey_0.22_all.click ./dontcrash.popey_0.22_all.click: pass Successfully built package in './dontcrash.popey_0.22_all.click'.

Which on my laptop took about a second.

Note the “pass” is output from the click-review tool which sanity checks click packages immediately after building, to make sure there’s no errors likely to cause it to be rejected from the store.

Testing on an Ubuntu device

Testing the click package on a device is pretty easy. It’s just a case of copying the click package over from my Ubuntu machine via a USB cable using adb, then installing it.

adb push dontcrash.popey_0.22_all.click /tmp adb shell pkcon install-local --allow-untrusted /tmp/dontcrash.popey_0.22_all.click

Switch to the app scope and pull down to refresh, tap the icon and play the game.

Success!

Tweaking the app

At this point for some of the games I noticed some issues which I’ll highlight here in case others also have them:-

Local loading of files

Construct 2 moans that “Exported games won’t work until you upload them. (When running on the file:/// protocol, browsers block many features from working for security reasons.” in a javascript popup and the game doesn’t start. I just removed that chunk of js which does the check from the index.html and the game works fine in our browser.

Device orientation

With the most recent Over The Air (OTA) update of Ubuntu we enabled device orientation everywhere which means some games can rotate and become unplayable. We can lock games to be portrait or landscape in the desktop file (created above) by simply adding this line:-

X-Ubuntu-Supported-Orientations=portrait

Obviously changing “portrait” to “landscape” if your game is horizontally played. For Don’t Crash I didn’t do this because the developer had coded orientation detection in the game, and tells the player to rotate the device when it’s the wrong way round.

Twitter links

Some games we ported have Twitter links in the game so players can tweet their score. Unfortunately the mobile web version of Twitter doesn’t support intents so you can’t have a link which contains the content “Check out my score in Don’t Crash” embedded in it for example. So I just removed the Twitter links for now.

Cookies

Our browser doesn’t support locally served cookies. Some games use this. For Heroine Dusk I ported from cookies to Local Storage which worked fine.

Uploading to the store

Uploading click packages to the Ubuntu store is fast and easy. Simply visit myapps.developer.ubuntu.com/dev/click-apps/, sign up/in, click “New Application” and follow the upload steps.

That’s it! I look forward to seeing some more games in the store soon. Patches also welcome to the template on github.

Categories: LUG Community Blogs