PygameFrame 3 - Game-Building Skeleton (using just Python and Pygame)
README and the rest of the initial project by Santo Ciaravino in 2013.
This is just a quick little readme and guide around the template.
---
BEFORE USING THIS PACKAGE, YOU MAY WANT TO GET THE FOLLOWING:
Python - To code with. For this updated release, I moved on to Python 3 (using 3.3.2).
http://www.python.org
Pygame - Can't make games easily without this. Get the one for the proper Python version.
http://www.pygame.org
---
When I started this as "Santo's Pygame Template", it was very crude, but it did the job. Then with some tweaking out of 2.5 and into 2.7, it started to appear even more solid and streamlined, but with the loss of two cool modules at the time: wxPython and Psyco. One helped crunch the code faster, and the other one was able to keep only one instance open for me. But having them together all the time was cumbersome. I decided to keep it simple.
In this release, it got even more... Diluted... For lightweight goodness. I also have it updated using Python 3. From what I understand, Python 2.7 is the latest and backport-friendly long-term supported version, and from my testing, it seemed to run fine. Still, everyone's experience will vary.
---
===DISCLAIMER===
As far as this goes, this package was made to help aid the aspiring game developer to use the popular open-source "Pygame" library. I wouldn't think any special licensing or whatever is necessary. If anything, at the very least, give me props for making this.
Because of the universal scope of game development, the material in this package can be modified at the user's will. The whole point of the template is to become the game that the developer wants... Or at least get a better grasp of how Python and Pygame work together.
Updates I have made from the second to this third one include:
# Chapters from the previous version are now Scenes.
# Main Loop (the one that runs the entire game) is now Core Loop.
# To the best extent possible, every part of the game, including the game itself, is now encapsulated as an object.
# I took off a lot of extra weight. Extra tools and folders and directories and stuff are gone, in favor of a much more 'bare-bones' environment as opposed to an all-inclusive one.
# Included framerate-independence (useful for physics-related sprites to move per second instead of per-frame) by replacing clock.tick to the top of a loop (because it still runs after update) and storing time information.
And of course, props to everyone who made Python to be such a great platform for programming.
===
---
===GUIDE===
Welcome to PygameFrame; my Pygame template package!
This project was originally known as "Santo's Pygame Template", coded in Python 2.5, but along with a new name, it got a major face-lift to stick to Python 2.7 conventions, and a huge clean-up of the code with new knowledge obtained of the Pygame package... And now, it's been made for Python 3 (using 3.3.2)!
I created this project because I wanted to make myself an easier and neater way to learn, and to use, the popular Pygame package to develop games, and there are no rock-solid Pygame SDKs out yet (at least none I know about). There is no uniform way of making a Pygame game, but I've seen different game scripts and components coded in so many different ways, that I decided to take the best elements, brush it up for myself to use, and put it together into this project; just because I believe in the old adage, "consistency is key".
And what better way to start building a new game than to copy-paste a whole package of files with all the framework I need pre-coded so I can do the work on the game with its parts, and not the internals of what the game runs on (or at least right away)?
Obviously this is not the most complete (or even cleanest) thing out there, and it could use a whole lot more (I don't know THAT much yet; sorry!), or it might not even work right; but making this project, along with all the research I did, helped me understand how a lot of Pygame's materials worked, and through the books and online info I've read, I've done enough re-tooling to make it function with some level of finesse (including a stereo-panning function, and a splash-screen effect).
This is the lowdown of the package:
No game can be made without a proper document outlaying what you intend to program. I included a .txt file for your use in writing your design notes. Or, grab your favorite word-processing program and make an entire design document; why not?
Pygame games can be written in one file (example included as simplegame.py), but if you got bigger plans, then you need serious modularity. That's why I built this package. Instead of running a game in one roll, beginning to end, now you can include more scenes to install more levels, store away tools, have save/load files, store massive collections of sprites, etc.
The entire package can be gutted and edited to your liking in the name of building your game. I only provided basic framework of the internals to help get running right away. Copy-paste the entire project, and now you have a new game framework, all set to go!
The game.py file is the mother file of the entire game package, and thus contains the heart of the game's equipment. You open this file, and the game runs. Pretty simple.
---
It runs the main loop that links all of the chapters you can use for your game. The trick here is to return information to a new chapter object's start() method, such as with a main-menu screen returning one value to open a different screen, or after a character is selected, pass it into a chapter's start() method to use that character in the game.
---
I find the console window displaying game information before the game starts to be a neat little formality (and it would also be nice if the guys developing Python could find a way to make it stay open if an error showed up instead of closing out to help you debug better). If you don't want it happening (suppose you finished building the game and you put the details in an "About" page, simply rename your file to end in .pyw instead of .py; as this will make it a "windowed" file. It is the exact same file with the same exact script, but the only difference is you won't get a console window.
---
DIR_data is where all of the data for the game is located; to isolate the main game file from the rest of its components. Inside this directory lies all the parts and pieces that help put together your game.
DIR_console contains the "hardware" of the game, including the screen, the audio system, the spriter (a device I made to help construct information for sprites), and even the joystick data. Although all of these can be accessed in the Pygame library itself, I made objects that work with them to help streamline and contain necessary information you can pass through in each of your chapters. For example, the video.show() method is a combination of pygame.display's flip() and update() methods, that can determine which one is appropriate to call on the screen's settings, and keeps it as one call.
DAT_newscene is a simple copy-paste file to create a new 'scene', which is simply a scene used in a game. You can make a scene that represents the main menu, the game actions, a level, game-over screen, credits, etc.
---
The reason that the scene files are located in DIR_data and not in their own directory is because they are the files that the resources beneath them are being used in. You can, if you wish, put the chapters in a directory of their own, but I found it more convenient to keep the chapters on top of the resources they use to prevent confusion with relative/absolute importing.
---
DIR_sprite contains all of the sprite image files the game uses. They can be done in the form of entire spritesheets, smaller spritesheets to detail an animation, or an image for every instance of graphic possible in the game. Your choice.
---
As the game developer, you can decide how to organize your sprite work. Do you want to use a main sheet image that contains every graphic you need? Or do you want to make individual separate files of each and every frame? The "Spriter" file (located in DIR_console), which is a sort of cookie-cutting device on graphics, can work in both principles, as long as you pass the correct parameters where necessary. Remember that it reads with ((x,y), (w,h)) for rect cuts.
---
While it is possible to write games without using the sprite objects, and there are times where it's better not to use sprite objects, I still provided the framework to make it as easy and accessible for almost any purpose as possible, purely for the purpose of streamlining screen updates.
---
DIR_new is simply a new directory, prepared with an __init__.py file and a new file, prepared like all the other files for a uniform build. Just copy-paste to have a new folder or file for whatever you need!
DIR_asset is a folder that contains 'asset' information, like game objects and their sprites. The reason for this is because in the old version of this kit, each resource had a dedicated folder (music, sprite image, etc.). But in some instances objects share resources, so the console tools were redone to be much more modular in handling where things like sounds and images go. Assets are what holds game objects; whether or not any extra resources are used.
---
A few suggestions you may want to look into:
1. Comment your code all the time! Keep your code clean, and even uniform. Notice how my 'keywords' for things use single quotes [''] and my longer texts use double quotes [""], to break the difference better. Camel-Casing is always helpful when it comes to methods [ie: object.newMethod()].
2. If you've looked around my template already, you'll notice how some of the things have three letters followed by an underscore, like "DIR_data". This is a neat little convention I came up with so I can tell what's what in my script, similar to how file extensions tell us what kind of file the file is (.jpg is an image, .mp3 is an audio track, etc.) I used this trick so as I code, I don't have to backtrack. Of course you don't have to use the trick, but it helps when you're coding a huge script. I provided another .txt file [Programming Conventions Index.txt] for a small list of some conventions you can use.
3. Use whitespace! It helps when code gets too difficult to read because everything is crunched in together.
4. Don't be entirely limited to what I wrote. Remember, I wrote this to help you out with coding. Use other modules and strip this template apart if you have to.
5. Docs are your friend. They helped me make this. Read them. Or read information anywhere you can get (like books or Internet). Or, even ask around for help.
6. I highly recommend using PNG for graphic files, and OGG for sound files. PNG includes alpha channels, which can help make translucent graphics; and OGG is fully capable with Pygame on any system.
7. Practice! If this template doesn't help, don't hesitate to keep learning some other way! Game design may just make a good idea, but game development (whether coding software or printing game boards) brings that "idea" to life. Don't give up!
===
---
Hope this package helps, and happy game coding! :)
~Santo C.
Download Latest Version
PygameFrame - Py3.zip (61.1 kB)
