Tuesday, December 17, 2013

GitHub Pages, Bootstrap, and markdown

Since I started to move the example code for my son's tutorials to GitHub, I decided to document the tutorials and functionality with GitHub tools.

I initially started with the README.md file in my GitHub repositories.  This required me to learn Markdown Syntax.  The syntax is straightforward and take about 30 minutes to learn.  GitHub has version for Markdown that they're call GitHub Flavored Markdown (GFM).

This was pretty fun since I could use lists, headings, and embedded images in the README.md file. 

I then noticed that there is a wiki link to the right of each repository.  I created a wiki for the lessons and even put the YouTube videos into the wiki.

Today, I found out that GitHub has a feature called Pages to create a full project site.  I created a video overview of Pages and wrote a blog post here.

I created a full website for my project repository in 6 minutes.

Since I was on a roll and had some spare time, I read more about GitHub Pages and realized that the web pages were stored in my repository on the GitHub server and could easily be updated with git.

To make a more dynamic web site, I looked at bootstrap.  I created a test site for json_loader using the Carousel template for Bootstrap.

I ended the day by watching this awesome video by  David Cochran of Twitter.

Friday, December 13, 2013

PGS4A Installation Tutorial

Just saw this tutorial by Shems Eddine on getting PGS4A running.  Installing pgs4a is a common question.

Since I haven't had problems with the installation and I am running pgs4a primarily on Linux, I haven't been able to help with this problems.  Please see Shem Eddine's Journal for some great tips.  The tutorial is focused on Windows, which is great for all you Windows programmers out there.

If you're still stuck, there's the pgs4a forum.

JSON Map Loader for Android Games Written in Python (Pygame and PGS4A)

I recently changed my son's lesson on 2D tile maps to focus on creating a json_loader that can read in different types of maps.  json_loader will allow you to quickly create 2D tile games on Android.  It is for children learning to program in Python.  The example loader is not intended for production applications.   You can create fairly large maps with Tiled and have your player explore a small fanasy world.

The full source code for the loader is available on github.

You can get the package at the link above or with git.
  $ git init
  $ git pull http://github.com/codetricity/json_loader

 There are three skeleton program to get you started:

Maze.  This is the only game that is fun enough to be playable.  If you add a timer onto this game and a way to save the time scores, you'll have a fully playable game.  Even with the basic skeleton, the game is still playable.  You can create several maps with Tiled and then have a series of simple map games on your phone.

Adventure Map.  The game is fully playable with the character moving around the screen with either a keyboard or touchscreen.  The game doesn't have a layer to find things such as treasure or monsters.  You'll need to add this layer and write the code to take an action such fight the dragon with a sword.  For an idea of what to do with a map game, see my son's game Swarm that he developed when he was 13 years old.  Note that Swarm doesn't use json_loader.  Each map was created with Python code, not with a map editor.  It took a while to build the different levels.

Scroller. I also started on a 2D scroller game using json_loader.  The player scrolls and can jump around the screen.  However, the platforms don't work.  The character will fall right through the platform in the air.  I wrote a number of blog posts on 2D side-scroller games.  Here's another one.

Once you get the code, run the example program with:

$ python main.py

The default screen size is 480 x 320.

You can load a different map by opening main.py in a text editor and changing:

    map_file = "maps/map.json"

    map_file = "maps/test_map.json"

If you use test_map.json, you will have a maze game.

If you want to experiment, you can use the unfinished scroller game with:
  $ python scroller_example.py

If you do create a game with json_loader, take a video of the game and put a link to the video in the comments.

Sunday, December 8, 2013

Slick Pygame / Ren'Py Game - Save the Date

Funny, challenging and mildly addictive.  Save the Date is short and it will be tough to play it just once.   If  your date ends in disaster, you'll want to give it another go.  My son played it about three times.  We haven't won yet.  The game is free and worth the short download and 30 minutes of time playing.

 Save the Date is written in Python, Pygame, and Ren'Py.  The game's author is Chris Cornell.  The impressive music is by Francisco Cerda.  Save the Date was was a 2013 IndieCade Nominee.

I believe that the author of Ren'Py is Tom Rothamel, the same person that developed Pygame Subset for Android.  Both of these projects are very high quality and are widely used by an active community.

Friday, December 6, 2013

Sharp and Clean Symbols from GLYPHICONS


As I was reviewing the Bootstrap site, I noticed that there were references to GLYPHICONS.  I like this type of clean icons and may incorporate some of them into future games.

There are different licenses available.  One of the licenses is for a free version of 470 GLYPHICONS and 50 GLYPHICONS Social that are distributed under the Creative Commons license.  The author is Jan Kovarlk.

Many games and applications are moving to a cleaner, simpler icon style.

Thursday, December 5, 2013

kivy - alternative to Pygame


I looked at pyglet two years ago in October of 2011.    Since that time, I haven't gone back to it.  I've been focused on Pygame Subset for Android.  As far as I know, Pyglet doesn't work on Android phones.  I also like the Pygame documentation more than the Pyglet documentation.

Another library, kivy, does work on Android.  It should also work on iOS.  I haven't tried it myself on either Android or iOS.  My son and I have used it on Linux and it does work great on Linux.

My son was able to build a pong game from the tutorial in one session.  Kivy has a lot of potential and I want to go back to it.

The reason I'm still using Pygame for my lessons is that my son is still getting used to object oriented programming.  With Pygame, the program is can be made more easily with one long block of code.  He can then go back to change the program components into functions or classes.

With kivy, he has to immediately start using classes.

Here's the basic "Hello, World" in Kivy.

While this is actually shorter than a Hello World program in pygame, it does require class instantiation, which is a bit difficult to understand for a young teenager.

The kivy documentation is also considerably weaker than the pygame documentation.  Since kivy is a younger project, I've also experienced more problems with getting the libraries to work all the time on my Linux system.  For example, when I updated Ubuntu 12.04 to the beta NVIDIA Driver, 325, kivy stopped working.  However, pygame was still working.  This may be due to an error with the NVIDIA driver GL implementation and have nothing to do with Kivy.  However, it does show that with less people using Kivy, more things can go wrong.

The advantages I can see for kivy are:

  • multi-touch support.  This is huge.  Pygame only supports a single point.  Although there are some hacks to use the joystick module to detect multiple inputs, it's not that clean a solution.  Getting multi-touch support is a major draw.
  • iPhone, iPad support.  It doesn't look easy to do and I've never done it.  There are some apps on the Apple Store.  So, it's possible to get it to work.  I'm sure it will get easier as the platform matures.
  • GPU acceleration.  The fancy OpenGL ES 2 support makes it easier to do cool 3D effects
  • Android and iPhone support is provided by the core maintainers.  For Pygame, we need to rely on the separate pygame subset for android project (which probably won't support multi-touch since the key developer wants to keep the feature set similar to what is on the base pygame library.)
  • The development community around adding features to the platform seems to be more active than the pygame development community.
The downsides for the purpose of teaching:
  • Pygame documentation is better
  • More people use Pygame and there are more examples of Pygame code
  • The larger pygame community means that most problems have already been solved by other people.  Much more answers on stackoverflow
  • Kivy uses the KV Design language in a separate file.  It gets a bit like JavaScript where you have multiple languages for one application.  There's upsides and downsides to this approach.  The main downside is that there's a slightly steeper learning curve for the kids.
Despite the shortcomings, I'm most likely going to revisit kivy in my curriculum after my son gets through his 2D Maze games.    This assumes that I don't start on django.

Tuesday, November 26, 2013

2D Tiles Games - More Algorithms to Slice Tilesets

Prior to heading out to go fishing, I came across this nice post on slicing a tileset into rows and columns.  The example uses Surface.subsurface, which I haven't been using effectively.

The author wrote a more elaborate tutorial here.

The author of bitcraft-PyTMX used the code below to handle tilesets.

I plan to review the code snippets above in more detail after the fishing trip.

Sunday, November 24, 2013

Pygame on Android App Crashes on Start: FIXED

A good tileset in the wrong place at the wrong time
After catching Jack smelt in Capitola and seeing an amazing display of seals, dolphins, and school of tens of thousands of fish, my son worked on his 2D tile map game, Maze.  The Android app consistently crashed on start.  It would display the initial splash screen and then die, leaving no error message.

This has happened in the past with other games.  We usually solve the problem with adb, the Android debugger.  Today, the fix was easy.  However, since I know that it can be daunting to wade through the adb logcat, I'll provide a few tips specific to Python / Pygame Subset for Android debugging.

My son's game uses Python and pgs4a.  He also uses Tiled to export JSON map files. 

First, find adb on your system.  It's not something that python developers normally use from the command line.  adb is in the platform-tools sub-directory of the android-sdk main SDK directory.

 From the Linux command line, you can either just run adb logcat or you can run it through grep and look for references to python.


 A larger snippet of the log file is shown below.

 In this case, the error was an incorrect reference to the tileset graphic.

The error is caused by a relative reference to a non-existent file.  Although the program works on the desktop, it doesn't work on the phone.  The fix is to place the tileset files in the same directory or sub-directory of your main.py program and create a new map and tileset with tiled.  If you've already created an extensive map, you can also edit the json file with a text editor to have it reference the correct location.

In this example, the file is called grass_water_terrain.png.

In a previous game, my son had a similar problem with the app crashing when it tried to load a font file that was in the wrong location.  Fonts and graphics are the two most common problems.  If you have all your fonts and graphic files in the same directory and your program still doesn't work on Android, but works on your desktop, you may be trying to import a library another directory.  Everything needs to be in the directory where main.py is or in a sub-directory.

If the application works on your desktop and it builds and then loads onto your phone fine, but crashes on start, think through what files the application is trying to load on the Android phone.  Then, work backwards and think through the differences between the phone directory structure and your desktop.  Also, think about the obvious things.  Check that you imported the android library and you've initialized it android.init().

If the problem is not immediately obvious, fire up adb and look for references to python.


  • import android library
  • initialize android library
  • main game file is called, main.py
  • graphic files are in the main or sub-directory
  • font files are in the main or sub-directory
  • custom libraries that you wrote are in the main or sub-directory

Update: March 3, 2014
One of the viewers of my pychildren YouTube channel had a problem with sound.  The important section is to map pygame.mixer and android.mixer to mixer.

try:    import pygame.mixer as mixer except ImportError:    import android.mixer as mixer

The other problem with sound is that there may be problems with different types of sound formats.  I suggest you use .wav files.  Since sound is handled differently on Android and the desktop, a few problems occur.

Tuesday, November 5, 2013

Pygame Subset for Android Sprite Optimization with RenderUpdates

In order to get 2D map games written in python working faster on low-end Android phones, I experimented with optimizations. I purposely selected a complex background image in order to stress the application.

The first set of huge gains came from using the Surface.convert_alpha() method to optimize the images. This was easy and resulted in significant performance gains.

The trickier part was to update only the sections of the screen that had changed since the last cycle.

I decided to use sprites for this since many of the optimization examples I've seen use sprites.  Instead of using pygame.sprite.Group, I used pygame.sprite.RenderUpdates.  This is basically the same as the sprite group, but it as the enhanced ability to track the changed areas of the screen.

The images in the group are drawn to the screen with the standard sprite.Group.draw(SCREEN) method.  The cool little addition is the RenderUpdates.clear(SCREEN, background) method which clears the sprite by blitting a piece of the background over it.  Nice.

The final section is to update the display with a list of the rectangles, pygame.display.update(rectlist).

That's the main things to change.  I experimented with not ticking the pygame.time.Clock under android.   I'm not sure if it makes a difference, but the application appeared to me to run slower on android when I used the clock tick.

This is the first time that I've used this bit of code to pause the android device when the user hits things like the home button on the phone.

I was pretty happy that my alpha transparency worked with the sprite group.

I also experimented with different ways to optimize the events. However, I couldn't find anything useful.

Here's the full code.

Monday, November 4, 2013

Paint Program with Pygame

My fourteen year old son did a nice job with his paint program. This took two or three lessons. He's making rapid progress now. He's quite busy with school and sports and doesn't have enough time to work on his programming. Despite the limited time he spends on programming, his cognitive skills are improving rapidly and he's able to build usable programs in a short amount of time. He was also able to incorporate feedback from his 8 year old sister. She designed the color palette and put a feature request for the stamps. I think she might have preferred flowers to the stamps.
This program uses Pygame and pgs4a.
Stay tuned for his next application, a JSON 2D map loader and maze game.

Sunday, October 27, 2013

Kivy, nvidia drivers and Linux Ubuntu 12.04

I sometimes wonder if I'm getting too old to fiddle around with Linux as my main desktop at home.   I'm no longer reading mailing lists or forums and my friends have all moved to Mac OS X.

Today was one of those days.  I fired up Kivy and PyCharm this morning, hoping to punch out a quick touch-paint example for my son's lesson.   Unfortunately, Kivy had stopped working, spitting forth odd complaints about [WinPygame] Video: failed.

After I figured out that the error was related to the nvidia 3D driver, I decided to rollback the video driver version from nvidia-325 to nvidia-current 304.  When I rebooted my system, I could no longer get into X, leaving me with a text console and odd errors complaining that the kernel module was still trying to load the nvidia-325 module.

At this point, I'm thinking that the coffee isn't kicking in, I'm getting too old, and that I don't really want to be messing around with kernel modules.  sigh.   I just wanted to write a python script.

After an hour of messing around with kernel modules and X configurations, I decided to simply add the xorg-edgers 3rd party repository into my apt repository list and use apt-get to install nvidia-325.

I reboot and kivy starts working again.

I am not sure what started the problem.  When kivy stopped working, Pygame was still working.  I suspect that the nvidia driver or some graphics library got automatically updated, causing some graphics problems with kivy.

I notice that the newest version of the nvidia driver is 331.  I don't think I'll upgrade it right now.

To revert to official packages, install the ppa-purge package and run "sudo pp-purge xorg-edgers"

Driver for Ubuntu 14.04 Trusty Tahr is nvidia-340.

Update September 12, 2014
I used this great blog post on installing the latest Nvidia drivers on Ubuntu 14.04 Trusty Tahr.

Monday, August 26, 2013

Tiled JSON Map Loader Example Code Available

Someone asked me for the source code for the JSON map loader example I created for a video tutorial on using Tiled to export 2d tile maps as JSON map files. Although .tmx is a more popular format, Pygame Subset for Android does not support the xml parser libraries.  Because of this, we can't use the TMX Loader library available on the Pygame site.  Pytmxloader also will not work.  This is unfortunate since the pytmxloader is especially nice.  Although these libraries will work on the desktop.  They will not work on the Android phone.  :-(

At some point, I was planning to write a library for JSON map file loading.  However, I never got around to it.  The code below will work on desktop and mobile phones.  It is for educational purposes only.

JSON Map Loader Lesson Code that works with Tiled maps.

Sunday, August 25, 2013

Installing Pygame Subset for Android

I noticed that a new version of pgs4a came out.  I upgraded from 0.9.4 to 0.9.6 this morning.  The process went smoothly on my Ubuntu 12.04 LTS system.  I was up and running in 10 minutes and my programs ran with no problems.

Since the installation on Linux normally goes fine, I suspect that many of the problems people have with pgs4a is not due to the installation, but due to usage.

Here are three common problems I've heard about:

1) You're not specifying the directory of your application.  Many people will configure and build the name of the python file.  This is wrong.  You need to specify the name of the directory.

The location specified after build is the name of the directory, not the file.

2) You didn't name your main python file main.py.   You may have called the file something like runner.py or angryfish.py.  This is wrong.  The file needs to be called main.py.

3) You didn't initialize the android library in  your python code.

Then, there are cases where everything should be working, but it's not. Assuming that you installed the android sdk with the command.

 then your adb tool will be in android-sdk/platform-tools.

The most useful command will be ./adb help followed by ./adb logcat.   With your phone connected to your computer with a USB cable, running ./adb logcat will give you the logs from your phone.  By reading through the logs, you should be able to get some clues as to why your program is failing.

Match Game Lesson, Lists and Dictionaries

New lesson on a match game with lists and dictionaries.

The code for this lesson is available on bit bucket here.

Friday, May 31, 2013

Lesson 6 - Putting it all together - Python tile game on Android

Middle school student teaches a lesson on getting a character to walk around a map.  The map was created with Tiled.  It is a single image saved in png format.  The character can now move in all four directions.

Sunday, March 31, 2013

Lesson 5 - Going Mobile - Python on Android

Part one covers Python code modification.  Part two covers Android phone settings and configuration of Pygame Subset for Android.

Part 1

Technical points of part 1:
  • import android library and handle exceptions
  • map keyboard ESC key to Android back key (hard button) on phone
  • quit game if phone back key is pressed

Part 2

Technical points of part 2:
  • Set Android phone to debug mode
  • Configure game build with pgs4a
  • Build, package, install
  • Test game

Saturday, March 30, 2013

Lesson #4: Mouse and Touchscreen Control (taught by middle school student)

Middle school student, age 13, teaches you how to get mouse control working on the moving square.
  • Goes through event queue to check for the mouse button. event.type == MOUSEBUTTONDOWN:
  • Checks for point collision with a rectangle: collidepoint(mouse_pos)

Monday, March 18, 2013

Lesson #3 - The Moving Square

Lesson number three teaches movement in the Y axis.

The main concepts:
  • Add 1 to the y axis to move down;
  • Subtract 1 to the y axis to move up;
  • Bounds checking to detect when the square reaches the edge of the screen;
  • Conditional to change direction;
  • Clock to set the maximum Frames Per Second (FPS) that the game runs at

Lesson #2 - The Stationary Square

This lesson focuses on drawing a stationary red square.  

Main concepts:
  • Colors are set by a three number tuple (red, green, blue).  Each value ranges from 0 to 255
  • Each point on the phone screen has two numbers associated with it, the x and the y coordinate.  A single point is a pixel.  The phone screen is 480 pixels wide and 320 pixels high.
  • The rectangle is initially set by the upper left corner.  The example uses (0, 0).
  • The width and height of the rectangle are measured in pixels, 64 pixels wide and 64 pixels tall.

Bonus concepts:
  • Graphics such as a cartoon girl are loaded with image.load("filename");
  • The graphic is displayed on the phone screen with blit;
  • The position of the graphic on the screen is established with a rectangle.

Lesson #1 - The Blank Screen

This is the first lesson in the Python and Pygame series.   It teaches the blank screen.   It is the basic foundation of all games.  This requires Python, Pygame, and a text editor.

This lesson was designed for middle school students.

Main concepts:

  1. Load and initialize the Pygame library;
  2. Set the size of the main screen;
  3. Create an infinite loop that runs the game until the player quits the game;
  4. Process the event queue;
  5. Handle the QUIT event;
  6. Update the screen.


Saturday, March 16, 2013

Teen to Teen: 2d Scroller Mobile Game Tutorial - Pavement

My teenage son produced a video to teach other teenagers to program.  This tutorial focuses on a moving pavement scene that scrolls from the right side of the screen to the left.  The complete code to the video is shown below.

Other videos that I made cover topics such as character animation to go with the moving pavement.

Posts on installing Pygame:

Sunday, March 10, 2013

2D Tile Game Map - Building the JSON Map File

I created a video of a very simple 2D tilemap game running on the desktop and an Android phone.  The video focuses on creating a json map file.  The video will take you through step four of the process listed below:

  1. Assemble tilesets which are pictures of grass, trees, water, rocks, bushes, houses and other graphics in the game;
  2. Assemble other sprites for graphics such as the character running around the screen;
  3. Create map data file using the Tiled map editor;
  4. Export the file to JSON format;
  5. Create a map loader in python;
  6. Use pygame to display graphics and handle player interaction;
  7. Use Pygame Subset for Android to package the Python application in Android Package format
I didn't cover how to write the map loader in this video since that video may take a long time.  The loader itself is less than a 100 lines of code.  The data structures are a bit more complex since Python loads the json file into the Python program as a nested dictionary structure.

Update Dec 2013:  Check out the code for an improved json_loader on github.

Sample game running with 2d map showing collision tiles shaded red.  Code and graphic files available on github

2nd layer of collision tiles separated out of the 3 layer map by test scripts in the game example.  Sample map included in the github package, available at the link above. 
Update December 13, 2013
Wrote a new blog post on using json_loader with examples of different types of games.

Sunday, March 3, 2013

Pygame Animation Tutorial Video

Here's a short howto video that starts off with a completely blank screen and takes you to a working animation.

I suggest you watch the video is full screen mode to see the text properly.

Sunday, February 24, 2013

2D Side Scroller with Pygame and blit


Since I'm still not completely recovered from the flu, I spent a few hours on Sunday working inside the house with my son on a 2D side-scroller game.  I'm still amazed at how quickly games can be created in Pygame.

To get the background to scroll, we used the Surface.blit method to slice up one large panoramic photograph.  We used Gimp to make the photograph look more like a cartoon.  This method is sometimes called, "one giant image."  The alternative method is to use tiles.  Since we used tiles for the background in the previous game, I wanted to try the "one giant image" method and see if it slowed down my son's phone.  Surprisingly, performance is completely fine.

In this implementation of the "one giant image" technique, we used the area argument of pygame.Surface.blit().  Most people use blit regularly with Surface.blit(image, rectangle).  Many people stop exploring blit with just those two arguments.  There's a few more tricks that are worth learning. 

blit will only use the upper left point of the rectangle as the point for the upper left corner of the surface.  The size of the rectangle doesn't matter.   A point such as (0, 0) will work the same as a rectangle.  The more interesting argument is the area argument that comes after the destination point.
Here's the method explained in the Pygame documentation.

The area argument can take a four integer tuple to slice from the source surface. For example (0, 0, 480, 320) will source the far left edge of the giant image and take a segment that is 480 pixels wide.  My son's phone has a screen that is 480 x 320.  We're using slices that are the same size as the screen of the phone .  By slicing a section 1 pixel to the right and then blitting that surface to the main screen, a stationary character in the game will appear to move 1 pixel to the right.   In the game shown, the character is a blue smurf.  The smurf is completely stationary on the x axis.  The smurf appears to be moving horizontally to the right because the background is moving horizontally to the left.  To enhance the illusion of movement, the smurf image rotates through a 16 cell animated sequence loop.

If the person playing the game looks at the town skyline in the background and the smurf in the foreground, the smurf will appear to move 1 pixel to the right every time through the loop.  The second time through the loop, the sliced area will be (1, 0, 481, 320).  The third time through the loop, the area will be (2, 0, 482, 320).   The game in the video is running on 30 frames per second.  The background is moved to the left at 30 pixels per second.

To create more of an illusion of movement, we're using parallax scrolling. Objects closer to the person playing the game appear to move faster than objects further away. The ground and cactus are moving toward the smurf at 8 pixels per cycle or 240 pixels per second. The larger trees are moving toward the smurf at 3 pixels per cycle or 90 pixels per second.  The tree is an actual photograph of a tree that was edited to appear more like a cartoon tree.

Update: 2014 February 20
Video tutorial available.

Saturday, February 23, 2013

2D Android Tile Game "Swarm" is Finished


Disneyland, the winter flu, soccer, surfing, school and work, these are all normal family activities.  Learning to program in python often seems to fall down on the priority list, especially for my teenage son, who is often boiling over with energy.  He'd rather be out running, hiking, fishing, or playing a team sport.

My son blocked out some time today for python programming and he decided to complete development of Swarm after finishing the eighth level.  Each level now has a different map.  He also changed the game fonts to more stylistic fonts he downloaded from the Internet. The video above shows all eight levels of his game running on a SamSung Galaxy Note II.

The levels are created with python code only.  He decided not to use a map editor since the map size is small and manageable.

There is a story behind the game.  The blue boy goes through different areas of the world looking for a girl that is imprisoned in a haunted castle.  If the boy gets through eight levels, he saves the girl.  A hero screen appears with the boy and girl enjoying a sunrise.

The next game he's working on is a 2d side-scroller game.

The distribution file and source code for Swarm are here.

Monday, February 4, 2013

Pygame Performance on Android Phones


The performance of python games is fine on old, cheap Android phones.  My son has written several games for his cheap LG Optimus S phone with 170MB of memory.  Although the games are slower than on a desktop, there are no problems with the speed of simple games on the phone.