0 votesclick to vote up

Stuart Langridge: Riddling: a puzzle game for Ubuntu phones Published Oct 29 2013 via RSS

planetUbuntu

My first app for Ubuntu phones is in the Ubuntu phone app store!

It’s called “Riddling“, and it’s a puzzle game involving intelligence, psychology, lateral thinking, research, and guesswork.

If you have an Ubuntu phone, you can get it right now: just search for “Riddling” in the Applications scope and install it. Let me know what you think.

Behind the scenes

If you just want to play the game, the rest of this post will not be of interest to you. I wrote Riddling partially because I think it’s a good idea for a game, but also to get some more detailed experience of the whole process of creating a completed application for Ubuntu phones: everything from the app review process to all the work you need to do outside core gameplay to make a decent app, and including the tools for building and checking applications, how to test them on the phone, and so on. So below I’ll outline some thoughts on this whole process. The basic summary is that building apps for Ubuntu is great and you should do it. There are still a few rough edges in the whole process, and so I’m writing them down in the hope that it’s useful feedback. Your thoughts, links to Launchpad bugs, disagreements, improvements, and war stories are invited.

App Creation

Apps for Ubuntu are created with QML. I personally, to make my biases clear, think it ought to be possible to develop almost any app using pure QML and JavaScript without any C++ involved. I don’t want to have to compile things, to think about different architectures, to ship more than one binary, to have to care about any of that stuff at all. You may feel differently, and you are welcome to do so, but be aware of my biases here: if your proposal for fixing issues that I bring up is “write C++”, “everyone should be compiling their apps from C++ anyway”, or something similar, then I’m going to disagree on those grounds.

On with the show.

“Ubuntu SDK”

One creates an Ubuntu app with the Ubuntu SDK. That makes sense: an SDK is a collection of APIs which your app can use. For Ubuntu, though, “Ubuntu SDK” is also the name of the IDE, the development environment: to make an app, you open the Dash and search for “Ubuntu SDK” and then run it. That makes a certain amount of sense, but it makes this really hard to talk about: questions such as “how do I run my app in Ubuntu SDK” sound strange, because it’s entirely unclear whether you’re talking about the APIs or the IDE. This is why developer environments have names: Visual Studio, Xcode, Eclipse. I wish the “Ubuntu SDK” was called an actual name.

“But it’s got a name!”, some of you will be saying. “It is Qt Creator.” Ah, but it isn’t. It is Qt Creator with extra stuff. I can’t just say to people “to make an Ubuntu app, run Qt Creator” because they won’t have the extra stuff. “To make an Ubuntu app, run Qt Creator and then install this other thing and this other thing and configure this thing and this other thing…” is the way to having people say, that sounds really hard so I’m not going to do that. This is why I wish that “Ubuntu SDK” was called something. Branding is important. The Ubuntu app development experience is not just “Qt Creator with an Ubuntu plugin”, or at least it can’t be if it’s going to be successful.

Custom build steps

Riddling is basically a game where you have to type in an answer for each level to proceed to the next level. Ubuntu users being what they are, a reasonable proportion of them will think, I can’t work out the answer for level 11, so I’ll just look in the source and get the answer from there. This would, obviously, spoil the game somewhat — the challenge is to research and think laterally, not to be a developer who knows what source code is — and so the game does not directly contain the answers; the game contains hashes of the answers and your entered answer is compared against that, in a similar way to how web services and Ubuntu itself check that your login password is correct without ever having a plain-text copy of that password around to check against. This is all well and good, but obviously I can’t be writing hashes all the time by hand. So my copy of the game contains the real plain-text answers, and when I build the game I take those plain-text answers and create the hashes of them to store in the released version. What this requires is a custom build step — a way to add an extra step to the build process as run by “Ubuntu SDK”, so I can add a step which does this answer encryption.

It is not possible to add a custom build step to the build process for Ubuntu SDK apps, at the moment. What this means in practice is that I have to write my own build process. I have a little shell script which does all the things I need: does the answer encryption, creates icon images from my original SVG icon, builds a click package. And I run that shell script instead of using the Ubuntu SDK thing. That’s quite annoying: it means that I’ve stepped almost entirely outside the Ubuntu SDK IDE at that point. (And indeed I’ve found myself doing most of my editing in my normal editor, Sublime Text.) To be clear, it is a credit to the Ubuntu SDK team that it’s perfectly possible to make Ubuntu apps without being forced to use the Ubuntu team’s choice of IDE. But I want to use their IDE — it’s all nicely integrated, it provides a whole bunch of stuff like device connection and code completion and debugging that others don’t — but I can’t because of this one blocker about custom build steps. All I’d need is some way to add a step which runs an arbitrary command: with that, I’d be golden. I spoke to some Qt Creator experts and it isn’t doable at the moment, but apparently it might be: this is exacerbated by how Qt Creator documentation basically assumes that you’re a C++ person and therefore “I want a custom build step” is “add something to your cmake file”, which doesn’t even exist if you’re writing a pure QML app as I think apps should be (and this one certainly should be, even if others shouldn’t). This feeling that “well, you’ll be writing C++ anyway, or you’re not a real programmer” does seem to rather pervade the community; it’s something that I hope Ubuntu can help fix.

Lint

“Linting” is the process of checking some code for accuracy and completeness. In this example, it’s about checking your built click package to confirm that it’s correct. Alan Pope pointed me in the direction of the excellent click reviewers tools: once I’ve built my click package, I do click-reviewers-tools/bin/click-run-checks com.ubuntu.developer.whoever_1.0_all.click and it gives me a bunch of information about the package and catches a bunch of errors. It’s incredibly handy: I was, for example, providing a full path to the qmlscene binary, and that works fine on my computer and also when running my app by hand on the phone, but it doesn’t work when running the app on the phone from the Dash. The click-reviewers-tools caught that error and I fixed it. That’s great. These tools need more publicity. I understand that they’re supposed to be integrated into the IDE build process at some point, which will be excellent (although it wouldn’t have helped me because of my custom build script, as above).

Documentation of QML

QML is quite well documented by the Qt project. The Ubuntu SDK components are mediumly-well documented by the Ubuntu team, and that documentation improves and gets more detailed every day, so I’m not worried about that. What is both confusing and annoying is that those two bits of documentation are in different places and are unconnected. For example, the documentation for an Ubuntu.Components.Label shows that the only thing you can customise about a Label is its fontSize. The example then sets text on it. What’s text? That’s undocumented? And how do I set the colour of the text? What about rich formatted text?

Well, an Ubuntu.Components.Label is actually an augmented QML Text item. The QML documentation for Text shows a zillion other properties that are settable, and to make any use of a Label at all you need to know that it’s really a Text but with extra stuff. The Label documentation doesn’t help with this at all. I only know that a Label is really a Text because I asked someone and looked in the source for the Ubuntu SDK itself. And if I look at the Text docs they say I can set font.pixelSize… but if I’m really a Label then I’m not supposed to do that; I’m supposed to set fontSize to one of the chosen Ubuntu sizes, for consistency across the platform.

The documentation being split like this makes it way harder to work out what to do. I think my proposed solution is that the Ubuntu documentation site ought to include the QML documentation too, so a Label lists all its properties, not just the ones that differ from Text, and explains why you should use fontSize rather than font.pixelSize.

This is a fairly mammoth undertaking, and I’m sure that the Ubuntu documentation team are aware of it and are working on it. For the moment it’s doable — as I say, I have successfully written an app — but I think it will confuse new app developers who are unaware that the Ubuntu SDK documentation only tells half the story, and the Qt QML documentation isn’t necessarily the best way to build Ubuntu apps.

Making a decent app

Part of the goal in writing Riddling was to really nail down the difference between “core gameplay” and “a finished app”. Riddling is ridiculously simple in concept: as mentioned, it’s just “allow the user to type in an answer and then check it against the list of answers”. I had the basics of the game implemented in, not kidding, 15 minutes. Everything else I did is bridging the gap between “prove the basic principle” and “make a game that people want to play”. All this bridging stuff is critical; it’s what makes the difference between a good idea and a good app. The idea (and the implementation of the idea) is about 5% of what makes an app good. Many open source apps haven’t quite grasped this and are just a bare implementation of the idea without the other 95% which takes it from idea to app. The Ubuntu philosophy is to do the other 95% too (whether that’s always succeeded is a different question, of course). So, for reference, here’s the list of other stuff I had to do to make Riddling once I’d made the core game in 15 minutes.

Work out how to encrypt the answers and encrypt them; add the “universal answer” which is accepted for every question so that I can test the game; choose a background gradient; choose font sizes; adjust the spacing between the clue, the text box, and the submission button on the front screen; work out how to convey the current level number; make the text box accept Enter to submit as well as pressing the button; add the list of previous answers; add an about page; have the app remember your current position when it’s closed and restarted; add a way to reset the game so you can hand the phone to your kids and they can play; add subtle sound effects for correct and incorrect answers; credit the freesound creators of those sound effects; add an animation transition to show a correct or incorrect answer; decide on the proper easing for those animations; write a one-line description of the game; write a longer description of the game; design an icon; make icons in various different sizes; decide on a licence; make a website of the game; take screenshots of the game; test the game on a phone; test the game on a desktop; decide how big the window should be on a desktop; upload new versions of the click package to the website; work out how to tell people about the app; post to G+, to reddit, to twitter.

None of that is to applaud myself for work; it’s to illustrate how much stuff still remains to be done once you’ve come up with an idea and then built a rough implementation of that idea. None of it is specific to building Ubuntu apps, either. I personally am enormously guilty of having an idea, knocking out a rough implementation of that idea, and then thinking to myself “cool, that works; turning that into an actual game is just a small matter of programming and is quite boring, so maybe I’ll just release this as it is”. That’s not acceptable now; I’m gradually starting to understand that.

Also: get a designer. My graphical guy (who would probably be called an “art director” if we were, say, Electronic Arts rather than just two blokes) went on and on about getting the typography and spacing right, and we went backwards and forwards on it repeatedly. And he’s right: it all feels better now. Thank you, Mike. If you need someone who’s great at this stuff, let me know and I’ll put you in touch.

Submitting the app

At this point, I’ve built an app, I’m happy with it, and I’ve got a click package for it. Time to add it to the store so other people can play it! This will therefore be a laundry list of little complaints about the smoothness of the app submission process. Before I start, though, I should say this: it is fantastic that I can make an app and submit it and have it show up in the store after about 20 minutes. The team who built this and who do the reviews deserve congratulation: everything I outline below is merely a slightly roughened corner on an otherwise good process, and I’m confident that most of these issues are already known and that all of them will be fixed. In particular, I believe that it should be possible soon to submit an app direct from “Ubuntu SDK”, meaning that this whole web-based submission process will largely go away (although for people doing custom builds it will still need to stay around, of course). I should say that even if submission-from-the-IDE becomes a reality, there should be a submit-to-the-app-store command line tool to do it as well (which would do all the same stuff), so people with custom builds can use it and you’re not wholly tied to the IDE.

On the first screen of submitting an app, you’re asked for an “application name” and a “package name”. I at first thought that the “application name” was the human name for my app (“Riddling”) and the “package name” was the techie computer name which the click package is called (org.kryogenix.riddling). However, the “package name” doesn’t allow dots in it. After being hugely baffled by this, I asked on IRC, and popey confirmed that the “package name” is the last bit of the techie computer name: that is, all my apps are “org.kryogenix.something” and the “package name” is the something. The “org.kryogenix.” bit is called your “namespace”, and you select it when you first sign up for app submission; the “package name” is then glued onto the end of your namespace to make the name that the click package is called.

You’re asked for a “tagline”, a one-line description of your app. There are four different places to describe your app: the “tagline” in the submission process, the “description” in the submission process, the “description” in your manifest.json file, and the “Comment” in your appname.desktop file. It is not at all clear what the difference between these is. This, I think, could be solved by showing, as part of the app submission process, what the app preview in the Dash will look like for users once the app is submitted. What I discovered is that the manifest.json “description” is currently ignored (but will presumably become important once submission is done from the IDE), the appname.desktop “Comment” is also ignored, and the “tagline” and “description” are shown one after the other in the Dash app preview when installing an app. So if you have a paragraph which describes your app, the “tagline” should be the first sentence of it and the “description” should be the remainder.

The submission process asks for a 256x256px PNG icon. This icon is used by the Dash when looking at an uninstalled app, but it is not used as the icon for your app once the app is installed. Instead, the icon used once the app is installed is the one named as Icon in appname.desktop. There’s no guidance as to the size that this icon should be (I have emailed the Canonical design team asking for such guidance as part of the ongoing App Design Clinics), but I can tell you that 64×64 is too small and your icon will be zoomed up and look blurry. I used the same 256×256 icon that I added in the submission process, and that worked fine: nice sharp icon on the phone.

The “required hardware” option in the submission process says “PC Only”, and that’s all you can choose. That puzzled me for a while — surely there should be a “phone” option? What’s the point of providing a dropdown for this if there’s only one entry in it? — but I assume that this will change later, so just choose “PC Only” for now.

Sadly, there is currently no way to install a click package on the Ubuntu desktop. The process of developing an app, making a click package, and submitting it is rather excellent, but it’s close to impossible to make your app also available to Ubuntu desktop users, which would massively increase the number of people who are able to use it. Even if an app is built with convergence in mind — if it alters its display for more screen real estate, as Karma Machine does, or if it’s happy running in a small window and there’s no need to change, as Riddling is — actually getting the app to desktop users can’t really be done right now. I understand the reasoning here; click packages will be able to be installed on the desktop in the next release, and that’ll be fantastic. Right now, though, apps you build are to all intents and purposes phone only, unless you’re prepared to provide a bunch of techie instructions about installing dependencies and checking out bzr branches, or you’re prepared to build a .deb package. This will be cool once it’s improved, but right now it’s annoying.

In summary

I’ve really enjoyed making Riddling (and from the feedback, people are enjoying playing it). It’s clear to me that all the moving parts of “the Ubuntu platform” are coming together to make something which is great to write apps for and easy to write and distribute apps for, and that’s what I want from my OS of choice. All the stuff I mention above will be fixed soon, I’m sure. Meanwhile, while you’re waiting for that, open up the Dash on your phone and search for “Riddling”. Maybe you’ll be the first to get to the end!