User:Bjordan/GSoC 2008

Jump to: navigation, search

Spray Play and the Google Summer of Code 2008

I'm Brian Jordan--see my introduction to the OLPC GSoC community here. I created Spray Play with my brothers Greg and Eric during the Boston Game Jam during the summer of 2007. At the end of the < 3 day development period, we demoed Spray Play for a group of local schoolchildren and their parents, and their enthusiasm for the game won us the OLPC Award, which included passes to the Game Developers Conference 2008.


(as submitted to Google Summer of Code)

This project proposes (a) cross-platform packaging scripts for the python physics API Elements, (b) a sound API for Elements that allows applications to tie sound effects to physics-based events such as collisions and friction, (c) a "sound sets" API for easily managing possibly repetitive sounds in Pygame, and (d) a conversion of the XO action game Spray Play to use the Elements engine, utilizing and providing an exemplary implementation of (a), (b) and (c).

The goal of this project is to drive and enhance physics-based activity development for the XO. Sound effects are often neglected in activity development, yet they provide rich feedback to users from all locales. Imagine, as would be done with (b), hearing the *crunch* of a box as it hits another [velocity], or the *scraaape* of a sliding object [normal force + contact]. Sound sets, as (c), are groups of sounds that are played in semi-random order so as to combat repetitiveness. Often, games make the mistake of using one sound effect for each “shot” or footstep. This makes games sound cheesy--the sound sets API addresses this problem and promotes good sound design in a simple manner.

Spray Play, a game first developed by me and my 2 brothers in one weekend during last year’s OLPC Boston Game Jam, does not run fast enough to play on the XO. Nonetheless, it won the "OLPC award" for the most fun to play game at the Jam after being tested by local children (and their parents). For (d), the newly created Elements physics API will be tested and utilized to make Spray Play usable on the XO, and will also serve as an exemplary implementation of cross-platform packaging (a), physics sound effects (b), and sound sets (c).

Project Summary

What is Spray Play?

Spray Play is a physics-based action game based on the board game Crossfire. Players (represented by an XO character) aim their character at the puck and spray (or shoot) projectile circles at it, attempting to move the puck into the scoring area on their opponent's side of the playing field. Shot balls stay on the playing field and slide to a collection area behind the XO characters.

Spray Play currently uses a quick-and-dirty collision detection algorithm for physics and includes sound effects bound to certain game events such as shooting (thwoop!) and ball-puck hits (clink!).

The game was originally developed during the Boston Game Jam and playtested by local schoolchildren (observed by their parents) brought in at the end of the weekend to rate games. Spray Play was rated the most fun game at the jam, and won the OLPC Award.

Spray Play has been tested on the XO, but was unfortunately found to be too slow to play reliably with enough balls to make it fun. This is due to both the algorithm used for collision detection and the efficiency of the functions used for drawing.


Spray Play playfield with computer player

Elements and Spray Play

Spray Play's speed problems will be addressed by rewriting the game using the Elements physics engine, which also allows for easy changing of drawing platforms.

Elements is a project that has recently implemented support for the Box2D physics engine. Box2D has been used to create physics demos such as MIT Sketching and games such as Crayon Physics. Elements is a SWIG wrapper around Box2D, and has been shown to run well on the XO (see: Physic_Engines/Speed_Tests). The functionality of Spray Play's current physics implementation is a subset of the capabilities of Elements, and the projects would be a perfect fit.

This week, I have been discussing this project with Chris of the Elements project and getting acquainted with the Elements codebase. The speed benefits that will be gained from changing to the Box2D physics engine may also be bolstered by Elements' modularization of drawing code. This will allow me to change the graphics engine used if testing shows drawing calls to be a significant bottleneck.

Puck Edit Phase

Currently, after a point is scored, Spray Play resets the game board with a different shaped puck. During the GSoC, I will implement a simple Crayon Physics-style drawing mechanism that allows players to draw their own shapes to be used as pucks.


After a point is scored, an "E" key and pencil icon will pop up on the screen for three seconds. If this key is not pressed, a random puck will be chosen from the default puck set.

If this key is pressed, the player will be in edit mode and allowed to draw a shape / group of shapes with their mouse on screen.


Drawing, much as was done with Crayon Physics and similar projects, will create rectangle-segment hollow shapes for Box2D.

A limited amount of ink for shape drawing will be available, both to cut down on edit time and control the possible complexity of the resulting physics interactions.


An icon reminder to exit puck edit mode ("E" key and OLPC joystick icon) will be displayed after three seconds of idle time after having finished a shape. After seven seconds, the game will automatically switch to play mode.

A discussion of the technical aspects of puck edit mode is included in the Development Discussion section of this document.

Physics Sound (API)

Graphics are only a piece of the puzzle that is creating an engaging, social game. The creation of a rich sound environment is a high priority for the development of Spray Play. In the most recent version of Spray Play, I bound sound effects to be triggered during ball shooting, puck hits, and ball to wall collisions. The difference in experience between playing with the sound off and sound on is staggering--sound feedback is vital to the game experience. But this game-logic-based sound design is only the beginning.

For GSoC, I will work with the Elements project to implement physics-based sound effects.

Imagine, playing with a physics based simulation, you hear the...

  • crunch as one box hits another (collision velocity)
  • whoosh of a puck that's been hit into a fast rotation (rotation speed )
  • scrape of a "metallic" triangle sliding on the ground (friction coefficient)
  • tap, tap, tap of a "marble" dropped from above (collision/elasticity)

GetAngularVelocity() GetLinearVelocity()

Sound Sets (API)

A common issue among sound design for videogames is that of repetition. The problem is eloquently described by Andrew Boyd, who noticed while working on the videogame Blood Wake:

The 'chain gun' sound presented a difficult problem. [...] We needed to make a rapid-firing weapon sound that was powerful and impactful, could be listened to for extended periods without becoming irritating, and was able to support multiple playback instances simultaneously.

Solutions for this problem of repetitive sound effects are presented in Boyd's article, the thesis "Computer Games - Problems with Audio" and "Footstep Sound Effects". Multiple versions of sound effects can be recorded or processed to sound slightly different, and then played back in a random (or semi-random to reduce doubling) order. As I did sound design for the games Kuku and 3D Pong during the Boston Game Jam, I made sure to provide multiple versions of each effect and instruct the teams on using simple random-play methodology.

To benefit others using pyGame and developing games (even other applications) for the OLPC, I will develop an API for sound sets--groups of multiple sounds to be played interchangeably in different modes (e.g., random, random weighted for non-repetition, and footsteps) to allow for simple, better sound design. Sets can have sound effects added, modes changed, and sounds played/stopped (one-time and continuous). Sound sets will operate with pyGame, with the goal of eventual integration into the pygame.mixer API.

Packaging (source, activity, exe and app, flv)

Though my most important goal will to be making an activity that is both coded to be exemplary (for Develop) and integrates well with the XO, packaging for use and development by non-XO owners has significant benefits for the OLPC, Elements, and Pygame communities.

To this end, the first phase of my summer will be devoted to using py2exe and py2app to successfully package an activity for the Windows and OS X platforms. The first portion of this phase will be to research, test and prototype template scripts for packaging this and other games implementing Elements/Box2d. It is a distinct possibility that users, having installed these pre-made packages, will be able to modify code portions and variables and contribute to the development of levels and the tuning of gameplay dynamics for Spray Play. In addition, this template will let others get involved with Pygame/Elements development, which would help drive game development on the XO.

The placement of this phase--the beginning of my summer--is important. It will allow me to provide easy to test examples of my summer's work at discrete steps along the way. It will also give Elements, a fairly young project, a platform to show the OS community what it can do.

Less a point of coding, and more of cross-platform enjoyment of Elements/Box2D, I will also be producing screencasts (video) of my application and Elements' features before and during the GSoC. These will be converted to flash video format (flv) for (mostly) cross-platform compatibility.

Spray Play and Develop

It is hoped that Spray Play will be a widely used and widely modified application. To that end, special consideration will be made with respect to the Develop activity and new programmers.

Gameplay-changing constants will be kept in the same place and easily modifiable. I will code with a pedagogical eye, ensuring that Spray Play's code is clean and correct. Classes will be well-designed and either extremely understandable (credit goes to python) or commented to make it so. More complicated code segments will be their own subclasses.

Games can be a great introduction to the possibilities of computer programming. With Develop's recent improvements, it is hoped that Spray Play will be a tool for teaching python (pygame) and physics (Elements) programming in the classroom.

Logistical Notes


I am an enrolled second year student at Wesleyan University, and will be enrolled in 2008-2009 as well.


I have been discussing this project and the portions that would improve the Elements project with User:crazy-chris. I have begun researching py2exe and py2app packaging with his support.

Development process / tracking (Google code)

The Elements team is currently using Trac/SVN provider Assembla to host their project. Spray Play is currently hosted on Google code, which provides an SVN repository.

Spray Play source code and associated premade XO activity, py2exe, and py2app packages will be committed (when working) along with each day's progress to SVN.


When the Google Summer of Code is over, several distinct deliverables will be finished:

  • Spray Play will provide XO users with a fun introduction to predictive physics and (with Develop), programming.
  • Elements will have a physics-based sound API.
  • Elements will have template scripts for OS X application and Windows .exe packaging.
  • Users of the Pygame project will have the ability to use a new Sound Set API, which may be integrated into the Pygame pending community approval.

Development Discussion

Elements/Box2D Sound

b2ContactPoint fields: id normal normalForce position separation shape1 shape2 tangentForce


April 7 - Application in to Google

April 21 - Approved proposals announced

April 21 to May 26 - Community bonding

Continue regular talks with #elements, #olpc-content and #pygame on freenode. Continue becoming familiar with Elements and Box2D code and keeping up to date with new changesets on Assembla. Begin researching py2exe and py2app packaging and continue talking with Chris from Elements, making sure sound integration has enough to work with from Elements/Box2D. Begin scripting py2exe/py2app packaging templates if time allows for it.

May 26 to June 2 - py2exe

Work to modify the pre-existing pygame py2exe build script to include pre-built Elements/Box2D packages. Use a pre-made Elements demo (e.g. convex shape drawing demo) for testing. Talk to Elements community about making exe demo available.

June 2 to June 9 - py2app

Work to modify the example py2app package aliens_app_example from pygame's repository into a template for including pre-built Elements/Box2D packages for OS X 10.5 and OS X 10.4. Use pre-made demo, as with py2exe for testing and showing Elements to those outside the dev community. If time allows, begin testing phase.

June 9 to June 16 - package testing

Test the limits of packaging methods--implement a method for py2exe and py2app packages to allow users to modify code and gameplay/physics variables from a text file (using python's eval()?). Write documentation for py2exe and py2app build scripts and make available to the Pygame/Elements community.

June 16 to June 20 - grace period

Tie up loose ends, allow wiggle room for unexpected challenges in porting and documentation.

June (16-20) to June 26 - research and draft proposal for physics sound API

Work with Elements team to determine possible Box2D sound triggers and draft up methods for implementing them. Write up API structure, propose as addition to Elements API to mentor and Elements community. Begin coding physics sound API if time allows.

June 26 to July 1 - code physics sound API

Code Elements physics sound API, being careful not to commit any non-working code to Elements (as certain portions may need to be placed within the Elements code). Use already-written API document as basis for documentation, and document. Use pre-made Elements demos as physics sound demos.

June 31 to July 7 - physics sound grace period, document and package

Finish up sound API documentation, use py2exe and py2app template scripts to produce standalone physics sound demos.

July 7 to 10 - research and draft proposal for sound sets API

Submit mid-term evaluation. Research and propose API for sound sets, working with #pygame and mentor. Look in to possibility of footstep timing auto-play function.

July 10 to 17 - code sound sets API

Code up sound sets API, continually getting feedback from the pygame and Elements projects.

July 17 to August 11 - Spray Play development

Begin by benchmarking Elements' performance on XO with a .png background as Spray Play uses. Test physics sound and sound sets performance on XO as well. Determine largest number of objects allowed for Draw Mode.

Recode Spray Play using Elements, including sound driven by the physics sound API using the sound sets API. Continue building source, activity, app and exe packages along the way.

Document Spray Play and ensure proper operation with Develop activity.

Test on XO laptop, optimize parameters for laptop.

August 11 to August 18 - Pencil down, bugfix and document!

Ask #elements and #pygame to submit a round of simple feature requests and bugfixes.

Make sure documentation for all portions of project (packaging, physics sound, sound sets and Spray Play) is complete.

Create flash video screencast of Spray Play for cross platform admiration of XO.