Setup and packaging tips (especially for first-timers!)

Cosmologicon on 2012/05/04 05:50
— edited on 2015/08/16 03:15

I started a list of suggestions for setting up and packaging your PyWeek entry. A lot of these are things that frustrate judges if you don't do them. I recommend you read the list once before the competition, and after you're done with the game and packaging it, come back and go down the list to make sure you remembered everything.

First off, you should read the PyWeek Rules, and it's recommended you use the Skellington linked to from there.
 
Setup tips:

• Your base directory should only contain files the player will open directly. This includes a text file about your game (usually called README.txt) and the python script you execute to start the game (usually called run_game.py). It can also optionally include executables for launching on various systems, and a screenshot. Everything else should go into a subdirectory. Often all source code will go in a directory called gamelib, and all data will go in a directory called data.
• If you're on Windows, respect case sensitivity of filenames. If the filename is image.png and your code tries to load image.PNG, it will fail in Linux.
• Similarly, don't use slashes or backslashes in file paths. Use os.path.join. Backslashes will fail on Linux, and slashes, while they should work everywhere, are not recommended.
• Consider alternate controls that work on non-QWERTY keyboards. If your game is controlled with WASD, why not let the arrow keys also control the game?
• Don't start the game in fullscreen mode by default.
• Don't make the default window size wider than 1000 pixels or taller than 700 pixels (including title bar)
• If you want to set options (like running in fullscreen mode) with command-line arguments, that's fine, but there's no standard set of arguments, so make sure you document them in your README.

README tips:

• Before packaging your game, read your README carefully to make sure the information is accurate. If you use the skellington, make sure you replace "YOUR TEAM NAME" with your actual team name, okay? The README should contain at least the following:
• The name of the game
• Your team name (or your name if it's a solo entry)
• Team member names
• The version of python that you developed on
• All dependencies of your game, and the version of the dependencies you used to develop
• How to run the game (again, it's recommended that this is python run_game.py, so it's especially important to mention if it's not)
• The controls/instructions for the game
• License information for your game, and for all the assets you used but didn't create. (This can alternately be in a separate file.)

Packaging tips:

• Don't include any file that the player doesn't need, like version control history, TODO.txt, packaging scripts, .pyc files, __pycache__ directories, and __MACOSX directories.
• Include any pure-python libraries (eg pyglet) that you use, since this will help with any version differences.
• Put all your files in a single zip file. The zip file should contain a single directory, which then contains all the files (ie, no tarbombs).
• Name your zip file and the main directory within it the same name as your game. Team name is also acceptable. Whatever you do, don't call them pyweek14.
• zip format is preferred over rar

After uploading your entry:

• Make a diary entry saying you've uploaded it, and asking for feedback. This is where people will usually post if they run into issues with your game. If your game doesn't have any diary entries, there's not really a good place to post for help.
• Upload at least one screenshot.
• Update your entry details so that the "Game name" field is actually your game's name.
• Put information that would be useful to judges in your entry's "Description" field. It can be very difficult to tell with PyWeek games what's a bug and what's an unimplemented feature. I recommend putting the following in your description (can also go in the README if you like):
• Any way that the game is incomplete, anything that will seem missing to the judges. (If the game mentions a boss battle that doesn't happen, or there's no ending screen.)
• This also goes for unimplemented features, items, characters.
• If there's no audio.
• Give us an idea of how long we need to play for or how far we need to get before we've seen enough of the game to judge it. The cold truth is some people are not going to finish your game. If you don't want anyone who only finished the first level to judge you, say so.
• If the connection to the theme is not obvious, maybe spell it out.
• There's some disagreement over what's acceptable to do during the 24 hours after the deadline. Bugs that cause crashes are generally seen as okay to fix. If in doubt, upload two versions of your game, one exactly as it was when the deadline ended, and one with any fixes you made during the 24 hours, and let the judges decide how to deal with it. If you upload more than one version, make sure to mark them both "final". (Only submissions marked "final" are included in the torrent, I believe.)

Okay, that's all I got. Any other PyWeek veterans, feel free to add your own.

(log in to comment)

Comments

mauve on 2012/05/04 06:41:

Lots of these problems could be solved better with distribute:

Game data can be loaded with pkg_resources; this doesn't then require os.path.join or anything.
Pure-python dependencies can be automatically installed.
setup.py will automatically generate a .tar.gz that can be automatically installed with pip.

Cosmologicon on 2012/05/04 06:47:

Sounds good. Do you want to make a "distribute 101" post with a list of everything someone would need to do to use it, for people who don't have time to get familiar with it before the competition?

Mat on 2012/05/04 08:31:

Good advice, thanks for putting that together :)

I just want to add that it's really easy to make key bindings etc configurable using the ConfigParser module.

For pyweek I wouldn't bother creating fancy menus to edit this stuff, but just making them possible to change could be the difference between a playable/unplayable entry.

Here is my config file from last pyweek: https://github.com/mwehtam/Pyweek-13--Mutant/blob/master/data/config.ini

Cosmologicon on 2012/05/04 15:43:

Yeah that's a good idea.

Also we're (almost) all python programmers here. If your key bindings are hard-coded in, you can just give the module name and line number if people want to tweak them. I like to hard-code all my (potentially configurable) settings in a settings.py module. People can tweak the numbers to make the game easier too, if they want.

BlueDragon on 2012/05/05 05:52:

Thanks for the tips!:)

illume on 2012/05/05 12:17:

It's a pity the packaging tips can't just be, "upload a python package to pypi".