Pycap

Pycap

Here it is... the ultimate framework for the super slack programmer. Pycap wraps the sweet sweet PopCap Game Framework in a super friendly high level python interface. With Pycap you can start building pretty 2D games without installing a compiler or learning C++. Have fun, and please let me know if you make something cool with it!

<3 Farbs

Getting started

You're in a maze of twisty little passages, all alike.
> INV
You're carrying: Guidebook
> READ GUIDEBOOK

Welcome, traveller, to the glorious land of Pycap. To start your adventure, try some of the actions described below.

Download Tools

First up you'll need to download Pycap. You can get the current windows distribution here. Just download the .zip file to your computer and unzip it somewhere on your hard drive. If you're a linux user check out W.P. van Paassen's tuxcap project, which ports the PopCap framework to linux and includes Pycap. Lovely.

If you don't have one already you'll want to pick up a decent text editor. In theory you could just use notepad or Microsoft Word, but in practice you'd be better off nailing your genitals to a polar bear. I use SciTE, which you can grab for free from www.scintilla.org.

Explore Pycap Distribution

The Pycap distribution includes some sample projects, the Pycap source, and a folder full of licensing guff. Have a look at each of the projects by running the associated .exe and reading the game.py source files. The Sample project shows the basics of Pycap in operation, and includes documentation explaining how everything works. The Template project is largely blank and makes a good starting point for projects of your own. The PetalHeroPrototype project is an experiment I built a while ago. It shows how a small game can be built using Pycap, but really I just added it in because I think it's pretty.

Start Your Own Project

Make a copy of the Template project, then edit the game.py file to start a project of your own. If your code crashes then read the err.txt file to see what went wrong. Print statements output to the out.txt file, which you can use to debug your project.

Fiddle With The Source Code

The source directory includes the source and project files required to build pycap using Visual C++ 2005 Express Edition. You'll need to download Python, the PopCap Games Framework, and an appropriate version of the DirectX SDK to build the solution. The currently supported versions of Python and the PopCap Game Framework are listed in the Version Information section of this document. Most Pycap games have been written with little or no modification to the Pycap source, however you're most welcome to make modifications to it. If you have any suggestions for modifications or improvements then please let me know. Reading the source is also a great way to understand how Pycap works, and recompiling it is the easiest way I've found to change the application icon.

Architecture Overview

Pycap's Bits

A Pycap game has four main bits: The application, the python game file, and the two python modules. The application is Pycap.exe, a simple program built on the PopCap Game Framework. Where usually an application built on the PopCap Game Framework would handle game logic, Pycap simply loads the game.py python script and tries to pass function calls to it every time an event occurs. This gives the python script the opportunity to respond to events like keypresses and game loops updates. The application also creates two python modules, Pycap and PycapRes, which the game script can use to interface back with the application. While the Pycap module is used to draw sprites and play sounds, the PycapRes module loads and unloads resources and provides metrics like font heights and image widths. With the application and the two Python modules it implements all supplied in this Pycap distribution, all you need do is fill the game.py file with pure gameplay goodness.

A less interesting part of the game.py file is its appIni dict object, usually declared at the start. This is read by the application on startup, providing it with important initialization data. Be sure to fill this out correctly, as items like company and product names may be used by Vista to determine paths for application data storage.

Python output is sent to a file called out.txt in the same directory as the application. Similarly, python errors are logged in err.txt. Again this isn't very interesting, but it is a bit important.

Pycap Module Reference

The following list describes all the functions declared in the Pycap module.

allowAllAccess( fileName )

Tell the OS that all users can view and modify a file. Required for Vista.

clearClipRect()

Clear the clipping rectangle.

drawImage( image, x, y )

Draw an image resource at pixel coords.

drawImageF( image, fx, fy )

Draw an image resource at float coords.

drawImageRot( image, x, y, angle )

Draw an image resource at pixel coords rotated by a given angle.

drawImageRotF( image, x, y, angle )

Draw an image resource at float coords rotated by a given angle.

drawImageScaled( image, x, y, width, height )

Scale and draw an image resource at int coords.

drawString( string, x, y )

Write a given string to the screen using the current font.

drawmodeAdd()

Set the drawing mode to additive.

drawmodeNormal()

Set the drawing mode to normal.

fillRect( x, y, width, height )

Fill a specified rect with the current colour.

getAppDataFolder()

Get the folder that game data should be saved to. Required for Vista.

getFullscreen()

Get whether the app is in fullscreen or windowed mode.

markDirty()

Mark the screen dirty and call a refresh. It's generally considered a good idea to not call this when your game is paused or your application doesn't have focus.

playSound( sound, volume, panning, pitch )

Play a sound, providing id, and optionally volume, panning, and pitch adjust.

playTune( tune, loopCount )

Play a midi tune, with optional loop parameter.

readReg( key )

Read an entry from the system registry.

setClipRect( x, y, width, height )

Set the clipping rectangle.

setColour( red, green, blue, alpha )

Set the draw colour. Use a value between 0 and 255 for each component.

setColourize( on )

Enable/Disable colourized drawing.

setFont( font )

Set the active font.

setFullscreen( fullscreen )

Set whether the app should be in fullscreen or windowed mode.

setTranslation( x, y )

Set the translation applied to all draw calls. This should be set inside the draw() function, before any draw events that you want to translate. Note also that the translation is cleared between draw calls.

setTuneVolume( volume )

Change the global volume for all midi

showMouse( show )

Show or hide the mouse cursor.

stopTune( tune )

Stop playing a midi tune. If not specified, all tunes are stopped.

writeReg( key, data )

Write an entry to the system registry.

PycapRes Module Reference

The following list describes all the functions declared in the PycapRes module.

fontAscent( font )

Get the ascent of a given font.

imageHeight( image )

Get the height of an image resource.

imageWidth( image )

Get the width of an image resource.

loadFont( fileName )

Load an image font from file, and return its resource index.

loadImage( fileName )

Load an image from file, and return its resource index.

loadSound( fileName )

Load a sound file, and return its resource index.

loadTune( fileName )

Load a midi file, and return its resource index.

setFontScale( font, scale )

Set the draw scale of an image font object.

stringWidth( string, font )

Get the width of a string drawn using a given font.

sysFont( faceName, pointSize, script, bold, italics, underline )

Create an instance of a system font and return its resource index. Every parameter after pointSize is optional.

unloadFont( font )

Unload a font created by loadFont or sysFont.

unloadImage( image )

Unload an image created by loadImage.

unloadSound( sound )

Unload a sound file from its resource index.

unloadTune( tune )

Unload a midi file created by loadTune.

Pony Fashion Break

Herbert Dupony

Herbert wears:
Pink body spray, $55
Dotty Smith Eyeliner, $25
#000000 Muzzle Shine and Hoof Polish, $16.75
Hair by Wacom

Herbert appears courtesy of PC Zone's Steve Hogarty.

Hook Reference

These are functions which you can declare in your game.py file. If found by the application they're called in response to various input and application events. Your gamecode exists as implementations of these functions.

loadBase()

This function is called first, and is a handy place to load the games resources. The game doesn't update while this is running however, so if you want to show a progress bar you'll need to do your loading in the update loop. For smaller games though I just load everything here. It's generally a good idea to import the PycapRes module here, since it's declared just before this function is called and is needed for all resource loading operations.

init()

This is called once on startup, after loadBase and before update or draw. Usually I use this function to initialize game data.

exitGame()

This function, if present, should return a value indicating whether or not the game application should terminate.

fini()

This is called as the application terminates, regardless of whether it was closed at the game's request (via exitGame()) or due to other user input like Alt-F4 or closing the application window. It's a good place to autosave game data and clean up dangling resources.

update( delta )

This is called every game frame tick, and is where the majority of your game logic will probably reside. The float value delta provides the number of 1/100ths of a second that have passed since the last tick. This number varies due to changes in things like the monitor refresh rate, variable render costs, and general machine performance. I highly recommend accounting for the variable timestep in your game code, as games that assume a fixed tick will play very differently on different computers.

draw()

This is called after update( delta ) but only if markDirty() has been called by the game since the last draw update. Most of the Pycap graphics functions can only be called from within the draw() function, and it is expected that all graphics operations would be performed therein.

keyDown( key )

This is called by the engine every time a key is pressed down. The key parameter is an integer identifying the key that was pressed. To determine the mapping between keys and identifying integers, simply add the line "print key" to your keyDown( key ) function, run the application, press the keys that you're interested in, and view the output in out.txt.

keyUp( key )

This is called by the engine every time a key is released. The key parameter is an integer identifying the key that was released.

mouseDown( x, y, button )

This is called by the engine every time a mouse button is pressed down. The button parameter is an integer identifying the button that was pressed. The x and y parameters give the game window location of the mouse pointer when the button was pressed.

mouseUp( x, y, button )

This is called by the engine every time a mouse button is released. The button parameter is an integer identifying the button that was released. The x and y parameters give the game window location of the mouse pointer when the button was released.

mouseMove( x, y )

This is called every time the mouse moves, and gives the new position of the mouse cursor in the game window.

mouseWheel( z )

Similar to mouseMove( x, y ), mouseMove( z ) is called to relay changes in the state of the mouse wheel. The difference however is that relative changes are given, rather than an absolute position.

mouseEnter()

This event is called by the application when the mouse enters the game window.

mouseLeave()

This event is called by the application when the mouse leaves the game window. Mouse based action games may want to pause when this happens.

onWindowed()

This event is called when the application changes from being in fullscreen mode to being windowed. This change can be triggered by Alt-Enter as well as the setFullscreen( fullscreen ) Pycap function, so I use this to keep the fullscreen/windowed option button in my games in synch wih the actual application state.

onFullscreen()

This event is called when the application changes from being in windowed mode to being fullscreen. This change can be triggered by Alt-Enter as well as the setFullscreen( fullscreen ) Pycap function, so I use this to keep the fullscreen/windowed option button in my games in synch wih the actual application state.

gotFocus()

This event is called when the application receives focus.

lostFocus()

This event is called when the application loses focus, usually because the user has minimised the game window, clicked on another application, or switched to another application via alt-tab. It's generally a good idea to pause your game when this happens.

Licensing

Pycap is a means of interfacing with the PopCap Games Framework, and therefore all licensing requirements for the PopCap Games Framework apply to its use. Licensing documentation for the PopCap Games Framework is included in the Licensing folder of the Pycap distribution. Pycap is provided for free and without any additional restrictions, warranties, or obligations. Although I've tried to ensure that this software is safe, reliable, and virus free, I make no guarantees about it whatsoever.

This product includes portions of the PopCap Games Framework (http://developer.popcap.com/).

Version Information

Pycap is currently at version 1.1, and is compiled using Python v2.5 and the PopCap Game Framework v1.3.

Version 1.1 Changes

Questions, suggestions, benign insurrections

This documentation and distribution is very much a work in progress, so there's lots that I haven't covered here. If you have any questions or suggestions then please email me. I'll help you out as much I can. I'll then compost your feedback into a fertile mulch, and use it to grow this page into a healthy, vibrant hub of information.

Site and contents © 2008 Farbs