Cocos2d is a free and open source game engine for the Python programming language. On a recent contract, I used the iPhone version of Cocos2d (in the Objective-C programming language). It worked fairly well, so I decided to try the original version. Unfortunately, the setup wasn’t quite as smooth as I would have hoped, and the installation instructions on the Cocos2d website are not terribly helpful, so below are the steps I followed to get it to work.
Please be aware that these instructions will not work forever. Different versions of software are not always compatible with each other, and there may be lots of updates between now and the time you read this. I’ve stated version numbers for each component below so you can compare with the versions you are installing.
1. Install Python (v2.5.4)
The first thing to do is install Python, and the important trap to avoid here is installing the wrong version. Apparently the best version to install for Windows is currently 2.5.4 (the official releases are up to 2.7, but Cocos2d doesn’t support that). You could install 2.5.5 if you want, but that would involve compiling some things yourself. Here’s the page about the release:
Scroll down that page a little to “Download the release” and “Windows”, then download and run one of the installers. I recommend installing the x86 version, even if you’re on a 64-bit machine, because it is generally more compatible with other programs at the moment.
2. Install pyglet (v1.1.4)
Some of the windows and multimedia functionality for Cocos2d is provided by the pyglet library. Thankfully it’s very easy to install and use. The latest stable version now is 1.1.4, although I’m sure you can install whatever version is latest at the time you read this. Here’s the download page:
Download and run the Windows installer from that page.
3. Install pygame – optional (v1.9.1 for Python 2.5)
I chose to install pygame as well, because it apparently provides Cocos2d with support for SDL audio as well. I believe pyglet provides some audio support as well, so it’s up to you if you want to install this. The current version just now is 1.9.1. Information is available here:
It is important to download the correct version for your Python installation. Under the “Windows” section, I used the one labelled “pygame-1.9.1.win32-py2.5.msi”. You can probably install the latest pygame version at the time you read this, but make sure it supports your version of Python.
4. Install PythonWin – optional (build 214 for Win32/Python 2.5)
I chose to install this IDE for Python to make things a little easier. It’s not essential, but working from a command line can be quite tedious sometimes! The downloads are available on SourceForge:
It’s very important to select the correct installer to download and run here. I used the one called “pywin32-214.win32-py2.5.exe“. The “214” number refers to the build version — you can probably download a more recent version quite safely if there is one. The “py2.5” refers to the Python version, so make sure that matches what you installed before.
5. Download Cocos2d (v0.4rc0)
The first part of this is easy — download the Cocos2d package from here:
The version at the time I downloaded it was 0.4rc0 (rc stands for “release candidate“). I recommend creating a folder on your main hard disk (probably your “C:” drive) and putting Cocos2d in there. Unzip it, and you’ll get a whole bunch of files and folders.
6. Install Cocos2d
This is where things get tricky. I couldn’t actually get any of the Cocos2d installation instructions to work. I got error messages when I tried to use the “easy_install” method, and there was no PYTHONPATH environment variable to work with.
One of the suggestions is to copy all the Cocos2d source code into every project you make, but that is very inefficient. Eventually I found a similar solution which relied on only a single copy of the Cocos2d source code:
- Open the folder where you installed Cocos2d
- Copy the “cocos” folder inside it
- Go to your Python installation folder (probably “C:Python25”)
- Open the “Lib” folder (NOT “libs”!)
- Paste the “cocos” folder in there
Python should now be able to find and use the Cocos2d engine without any problems.
Test it out
Now that you’ve installed everything, it’s a good idea to test it. Start by launching the PythonWin IDE, which you can probably find in your Windows menu under “All Programs -> Python 2.5 -> PythonWin”. Follow these steps:
- Click “File -> New”
- Select “Python Script” and click “OK”
- Copy and paste the Hello World example code into your script
- DELETE everything above (but not including) “import cocos”
- Click “File -> Save As…” and save your script to disk (name and location don’t matter)
- Click “File -> Run”, and then “OK”
If all goes according to plan, you should see a window pop-up saying “Hello World”. Congratulations! You have got Cocos2d installed and working.
In case you’re wondering why you had to delete some code from the script, it’s because the original “Hello World” script was designed to run from the Cocos2d samples folder. The code you deleted was supposed to allow it to run without needing to fully install Cocos2d. Unfortunately the code doesn’t fully work in some editors, such as PythonWin, so leaving it in gives error messages.
I recommend having a look at the Cocos2d Programming Guide. It will give you plenty of information to get started programming your own games.