Python for Android Tutorial #5 – Our first Mobile Game with Kivy!!


This is the fifth post about mobile development with Python.

In this  post, we’ll code our first mobile game with Kivy! Android and iOS game development with Python?? Wow! Really nice, hum? So, let’s check this out!

Python Mobile course

I - About the Tutorials

I’ll show you how to use each mobile API, like compass, camera, sensors, sound, and others. After the API, we will start to test some Python libs, as PyGame and OpenCV. I’m using Android with buildozer, but major part are compatible with iOS as well.

Must read:

Source code

Get updates Follow @aron-bordin
Star it: Star
Contribute: Fork
Download: Download

II - Index

Available tutorials:

III - About this tutorial

This is a big post, to work in this game, we are going to learn and use a lot of Kivy.

But don’t worry, I’ll be writing around more five posts related to this one, explaining more about each component used in this game, like how to save scores, how to monetize your Kivy app, how to work with multiple scenes and more.

You can download and test our app here:

This is a simple game. You’ll see a grid in the screen, and some buttons will blink some times. Then it’ll stop to blink and you need to remember what was the last block to blink.

It’s a simple and nice example to help you learn more about Kivy. So, let’s start right now!

IV - UI -

Just I’d like to thanks , I’m not a designer, and in this kind of project, this website can be very useful :).

I used these links to this game:

I edited these files with Gimp and Inkscape, if you want to edit something, open the design folder and get the files.

V - Create your project

Go to a folder and add two files, and main.kv.

Now, run:

buildozer init

to configure buildozer.

VI - Game interface

The game is divided in two screens, the menu and the game screen.

Menu Widget Ids

You can check the id of each widget with the yellow color. The game interface was created with kv. In your main.kv file, add the following code:

id: background
source: "res/background.png"
allow_stretch: True #image in fullscreen
keep_ratio: False #image in fullscreen
id: title
source: "res/title.png"
pos_hint: {'top': 1.3}

id: label_best
text: 'Best score: 1'
font_size: '27sp'
pos_hint: {'x': 0, 'y':0.15}

id: new_game
source: "res/new_game.png"
on_press: root.new_game()
size_hint: 0.6, 0.15
pos_hint: {'x': .2, 'y': .4}
allow_stretch: True #image full the button
keep_ratio: False #image full the button

id: share
source: "res/share.png"
on_press: root.share()
size_hint: 0.6, 0.15
pos_hint: {'x': .2, 'y': .25}
allow_stretch: True #image full the button
keep_ratio: False #image full the button

id: exit
source: "res/exit.png"
on_press: root.exit()
size_hint: 0.6, 0.15
pos_hint: {'x': .2, 'y': .1}
allow_stretch: True #image full the button
keep_ratio: False #image full the button

In this source, we used allow_stretch: True and  keep_ratio: False so the image can fit the parent widget. The background fits the layout and the ImageButton fits the Button.

We use pos_hint: {‘x’: value, ‘y’:value} to place our widget in the screen.

The size_hint: 0.6, 0.15 resize the width to 60% of the parent and height to 15%.


You can check the id of each widget with the yellow color. The game interface was created with kv. In your main.kv file, add the following code:

source: "res/background.png"
allow_stretch: True #image in fullscreen
keep_ratio: False #image in fullscreen

id: label_level
font_size: '25sp'
pos_hint: {'x': 0, 'y':0.45}
id: label_last_block
text: ''
font_size: '20sp'
pos_hint: {'x': 0, 'y':0.35}
id: label_best
font_size: '20sp'
pos_hint: {'x': 0, 'y':-0.4}

id: back_menu
pos_hint: {'x': .75, 'y': .9}
source: "res/menu.png"
size_hint: .23, .08
allow_stretch: True #image in fullscreen
keep_ratio: False #image in fullscreen
on_press: root.go_menu()

id: restart
source: "res/restart.png"
size_hint: .23, .08
allow_stretch: True #image in fullscreen
keep_ratio: False #image in fullscreen
on_press: root.restart()
id: game_grid
cols: 2
rows: 2
size_hint: 0.9, root.width*0.9/root.height
pos_hint: {'x': 0.05, 'y': (1 - root.width*0.9/root.height) / 2}

Now, the game grid is empty. We’ll fill it with the Python code.

VII - Game code

Now, we can code it.

As I told you, this is a big post and we have a lot of important thing in this code.

So I’ll create more posts to explain each component. I’ll post about sounds, files, how to monetize the app and how to manage multiple scenes.

From now, I commented everything possible in this code, so I hope that is easy to understand. If you have any question, feel free to ask here :)

# Some resource that helped a lot :)

from kivy.utils import platform
from import App
from kivy.uix.floatlayout import FloatLayout
from import SoundLoader
from kivy.uix.behaviors import ButtonBehavior
from kivy.uix.image import Image
from import ObjectProperty
from kivy.lang import Builder
from kivy.clock import Clock #clock to schedule the game update
from import JsonStore
from os.path import join
import random

if platform() == "android":
from jnius import cast
from jnius import autoclass
from revmob import RevMob as revmob

#here we create a custom class called ImageButton. It's a image, however with
# some button properties. We use this class to use the on_press event
class ImageButton(ButtonBehavior, Image):

# This is the App screen, all game scenes(menu and the game) extends this object
class AppScreen(FloatLayout):
# MainApp referece, so we can call some functions provided by this object
app = ObjectProperty(None)

# This is our menu screen.
class MenuScreen(AppScreen):
def __init__(self, app): #init the object, receiving the MainApp instance
super(MenuScreen, self).__init__() = app # get the MainApp reference

# switch to the GameScreen
def new_game(self):'game')

# just close our application
def exit_game(self):

# App share with Android
# It will open an intent to share a message
def share(self):
if platform() == 'android': #check if the app is on Android
# read more here:
PythonActivity = autoclass('') #request the activity instance
Intent = autoclass('android.content.Intent') # get the Android Intend class

String = autoclass('java.lang.String') # get the Java object

intent = Intent() # create a new Android Intent
intent.setAction(Intent.ACTION_SEND) #set the action
# to send a message, it need to be a Java char array. So we use the cast to convert and Java String to a Java Char array
intent.putExtra(Intent.EXTRA_SUBJECT, cast('java.lang.CharSequence', String('Fast Perception')))
intent.putExtra(Intent.EXTRA_TEXT, cast('java.lang.CharSequence', String('Wow, I just scored %d on Fast Perception. Check this game:' % (self.best_score))))

intent.setType('text/plain') #text message

currentActivity = cast('', PythonActivity.mActivity)
currentActivity.startActivity(intent) # show the intent in the game activity

# will be called when our screen be displayed
def run(self):
self.best_score ='score')['best'] # get the best score saved
self.ids.label_best.text = 'Best score: ' + str(self.best_score) #show it
if platform() == 'android': # if we are using android, we can show an ADs
if(random.randint(0, 5) == 1): # get a random and show a ads in the menu

#Our game screen, where everything happens :)
class GameScreen(AppScreen):
def __init__(self, app): #init the object, receiving the MainApp instance
super(GameScreen, self).__init__() = app

#initialize defaults values to start a new game
def init(self):
self.level = 1 # the current level
self.best_level ='score')['best'] # best level
self.game_grid = self.ids.game_grid # the game grid widget instance
self.label_level = self.ids.label_level # the label widget to show the current level
self.grid_size = 2 #we are using a grid layout to show our blocks, the fist level has a 2x2 grid
self.last_id = None #last btn blinked
self.remain_interaction = 4 # number of blinks before turn off
self.can_click = False # if the user can choose a block. Only true while not blinking

# called when the game scene be displayed
def run(self):

# start a new game round
def start_game(self, dt = None):
self.can_click = False #while playing, user cannot choose a block
self.ids.label_last_block.text = "" # clear the id of last blinked block
self.check_best() #check if user has a new highscore
self.ids.label_best.text = 'Best level: ' + str(self.best_level) # show the best score in the screen
self.ids.restart.pos_hint = {'x': -1, 'y': 0.025} #hide the restart button
Clock.unschedule(self.update) # stop updating the game screen

self.label_level.text = 'Level: ' + str(self.level) #show the current level

self.remain_interaction = random.randint(2 + self.level/2, self.level*2) #generate a random number of interactions

self.draw_screen() #show the blocks in the screen

# here we set the speed of the animation
if self.level < 10:
interval = 1 - self.level*0.1
interval = 0.1 - self.level*0.001

#update the screen using the interval calculated above
Clock.schedule_interval(self.update, interval)

#each update a different block will blink
def update(self, dt):
# when last_id is not none there is a green block in the screen
if(self.last_id is not None):
self.game_grid.ids.get(self.last_id).source = "res/block.png" #turn off the block

if self.remain_interaction == 0: #if executed all interactions
Clock.unschedule(self.update) #stop updating the screen
self.ids.label_last_block.text = 'Click in the last block that blinked' #ask user to click in a block
self.can_click = True # allow the click

#if we can still blinking:

id = 'btn_' + str(random.randint(0, self.grid_size*self.grid_size-1)) #generate a random int to blink a random block
self.game_grid.ids.get(id).source="res/block_blink.png" #make this block border green
self.last_id = id # save the id of the green block
self.remain_interaction -= 1

# draw the blocks in the screen
def draw_screen(self):
self.game_grid.clear_widgets() # this command remove all children(blocks) from the game_grid

# according to the level, we can change the size of the grid
if(self.level < 3):
self.game_grid.cols = 2
self.game_grid.rows = 2
self.grid_size = 2
elif self.level < 5:
self.game_grid.cols = 3
self.game_grid.rows = 3
self.grid_size = 3
elif self.level < 10:
self.game_grid.cols = 4
self.game_grid.rows = 4
self.grid_size = 4
elif self.level < 15:
self.game_grid.cols = 5
self.game_grid.rows = 5
self.grid_size = 5
elif self.level < 20:
self.game_grid.cols = 6
self.game_grid.rows = 6
self.grid_size = 6

# this is a block in KV lang.
btn_str = '''
source: "res/block.png"
allow_stretch: True
keep_ratio: False'''

# generate a grid_sizeXgrid_size grid
for i in range(0, self.grid_size*self.grid_size):
btn = Builder.load_string(btn_str) # create a ImageButton from the string
id = 'btn_' + str(i) = id # set the button ID
self.game_grid.ids[id] = btn #add this button to the list of children of the GameGrid
btn.bind(on_press=self.on_btn_press) # bind the press event
self.game_grid.add_widget(btn) # and show this button on the grid

# grid button event
def on_btn_press(self, btn):
if(self.can_click is True): # check if the user can click
self.can_click = False
self.game_grid.ids.get(self.last_id).source = 'res/block_blink.png' # blink the clicked button
if( == self.last_id): # if the clicked button was the last one to blink
self.ids.label_last_block.text = 'Right!' # the user was right
self.level += 1 #user can go to the next level
Clock.schedule_once(self.start_game, 1) #wait a second and start the next level
self.ids.label_last_block.text = 'Wrong :(' #user was wrong
self.ids.restart.pos_hint = {'x': 0.75, 'y': 0.025} #the restart button is visible now

# compare the current level with the highscore
def check_best(self):
if self.level > self.best_level:
self.best_level = self.level'score', best=self.level) #save the best score. We are saving it in the key 'score', in the child 'best'

# open the menu screen
def go_menu(self):

# restart the first level
def restart(self):

# This is the main app
# This object create our application and manage all game screens
class MainApp(App):
#create the application screens
def build(self):

data_dir = getattr(self, 'user_data_dir') #get a writable path to save our score = JsonStore(join(data_dir, 'score.json')) # create a JsonScore file in the available location

if(not'score')): # if there is no file, we need to save the best score as 1'score', best=1)

if platform() == 'android': # if we are on Android, we can initialize the ADs service

self.screens = {} # list of app screens
self.screens['menu'] = MenuScreen(self) #self the MainApp instance, so others objects can change the screen
self.screens['game'] = GameScreen(self)
self.root = FloatLayout()


self.sound = SoundLoader.load('res/background.mp3') # open the background music
# kivy support music loop, but it was not working on Android. I coded in a different way to fix it
# but if fixed, we can just set the loop to True and call the play(), so it'll auto repeat
# self.sound.loop = True It # was not working on android, so I wrote the following code: # play the sound
Clock.schedule_interval(self.check_sound, 1) #every second force the music to be playing

return self.root

# play the sound
def check_sound(self, dt = None):

# when the app is minimized on Android
def on_pause(self):
self.sound.stop() # the stop the sound
if platform() == 'android': #if on android, we load an ADs and show it
return True

# when the app is resumed
def on_resume(self): # we start the music again
Clock.schedule_interval(self.check_sound, 1)

# show a new screen.
def open_screen(self, name):
self.root.clear_widgets() #remove the current screen
self.root.add_widget(self.screens[name]) # add a new one
self.screens[name].run() # call the run method from the desired screen

if __name__ == '__main__':

To help you understand the game logic. The user always start on the first level.

Then we draw some blocks in the screen and blink them calculated times.

After it, the user must to click in one of the blocks.

So we check if the button clicked is the same that we expect, if so, we just move to the next scene.

To manage multiple scenes, we load each of them in a variable. So we just add the desired screen to the MainApp widget and show it.

To monetize this app, we are going to use

They officially support Kivy apps, so it’s easier to work with it in this post. Just download this file: , move the libs and revmob folders to your project root and go to the next step.

VIII - Configuration

This app will need some special configurations, because we are using the revmob to monetize it. Open your buildozer.spec file and add the following permissions:


Now, to add the revmob API, add the following line:

android.add_jars = %(source.dir)s/libs/*.jar

Add Pyjnius

requirements = kivy, pyjnius

And, as we are using a .mp3 file, add .mp3 in this line:

source.include_exts = py,png,jpg,kv,atlas,mp3

And finally, set your app version with

version = 1.0.0

You can read my full buildozer.spec here:

IX - Running our Python game on Android and iOS

Now, we can run it and check if anything is working.

It’s a really big post, so if you have any problem in any step, feel free to comment here.

I tested only on Android, but it’s probably going to work with iOS too.

To run this game on Android, use the following command:

buildozer --verbose android debug deploy run

To run this game on iOS, use the following command:

buildozer --verbose ios debug deploy run  

Or, just type python to run it on your PC.

That’s it. Thank’s for reading!

Aron Bordin

Aron Bordin
Computer Science Student and AI researcher. Always coding something fun :)

[Tutorial] Developing Android Background Services

### Welcome!In this post, I'll show you how to develop background services on Android Studio. We'll see two type of services: `Service` a...… Continue reading