-
Notifications
You must be signed in to change notification settings - Fork 0
Framework Walkthrough
A.K.A, how to make anything work? This will show you how by discussing almost everything in core.py
In theory, something like the following should give you a correct, albeit useless, PyGame app:
from components.core import *
config = GameConfig()
model = GameModel()
screen = GameScreen(config.get_config_val("window_size"), model)
loop_events = GameLoopEvents(config, screen)
loop = GameLoop(loop_events)
loop.go()
The created objects are explained below. Note that in actual usage, you may want to take in different arguments for your components. The descriptions below describe the classes as written in components.core.
GameConfig contains settings for games. By default there three available settings: window_size, window_title, and frame_rate. You can add more settings via set_config_val and retrieve them via get_config_val. You can also set other components of your game to be notified when a particular configuration value changes by subscribing them to the config.
After deciding your game's settings in GameConfig, you can then subclass...
GameModels are the loosest components in terms of form. The purpose for these objects is to keep track of the state of the game. Beyond that, a GameModel is required to have a render function, taking in arbitrary arguments. Other components of the framework may call this function to help render the game screen. The render function must return an object which your GameScreen knows how to render.
The constructor for GameScreen takes in an argument for the screen dimensions and an instance of the GameModel to represent. Screen dimensions is expressed as an iterable (list, tuple, etc.) which has at least two elements: the width and the height, in that order. By default, in case your iterable has more than two elements, GameScreen will expect them to be the first two elements.
GameScreen is responsible for loading and drawing all the elements of your screen. Instantiate all PyGame Surfaces in setup. Then, override draw_screen to draw all that needs to be drawn. At the end, the most you should have with GameScreen are some animations. No user control.
Because to add user control you must subclass...
The constructor for GameLoopEvents takes in a GameConfig object and a GameScreen object. There are several methods in GameLoopEvents which you must note.
First, you need to define the condition for which your main game loop should keep on going in method loop_invariant. This method simply returns a boolean on whether your loop should proceed or not. In the current code at the repo head (and not in Milestone 1; see more in the discussion about event handling below), GameLoopEvents uses loop_invariant to manage the pygame.QUIT event (i.e., the event triggered by clicking on a window's "close" button), so, unless you want to handle pygame.QUIT yourself, extending classes are advised to call on their parent's loop_invariant method and and the result with their own invariant condition.
Next, you need to mind the objects which you need in your loop. Surely, it won't do to instantiate them on every iteration of the loop. For that you have the loop_setup method. This method is called after the PyGame display has been invoked and before the loop (of course).
Finally, you can define what happens in the loop by overriding loop_event.
The GameScreen is drawn by the loop_event method of GameLoopEvents (the main one, not just any GameLoopEvents class). Therefore, when extending any GameLoopEvents class, it is important to call the parent's method so that it eventually cascades to drawing the screen.
To handle events, override attach_event_handlers and call add_event_handler from there. add_event_handler expects two arguments. The first one is the PyGame Event object to be handled. The form of the second argument depends on the event.
For mouse events (e.g., pygame.MOUSEBUTTONDOWN) the second argument is expected to be a function. If it is pygame.KEYDOWN (key press event), you need to pass an instance of GameLoopEvents.KeyboardHandlerMapping. It has two parameters:
-
keycodeto indicate the key that must be handled -
handlerthe handler function---same provisions as the function you pass for the second argument for mouse events.
A list of key codes (that which you associate with GameLoopEvents.KEYCODE) can be found here.
Handler functions should expect one argument for the event (not counting self, if present).
Note: Text below applies to the current code in the repo head and not for Milestone 1.
As noted above, the pygame.QUIT event is handled automatically. However, there's nothing preventing you from overriding this behavior. If, for some reason, you need to quit the program other than from pygame.QUIT, the stop_loop function has been provided. stop_loop takes one argument and is the default function invoked for pygame.QUIT. That said, stop_loop assumes that the argument passed is a PyGame event object but it does not use it anyway so you can pass anything you like.
(Actually, stop_loop, as the name implies, stops the game loop and does not actually stop the program/close the window. However, as per PyGame Objects default behavior, pygame.quit() is invoked right after the loop.)
As with everything in Python, I assume that we're all adults here and that no one overrides stop_loop. But if you really need to do so, make it so that it will have no need for it's sole parameter. Otherwise, things may break for you.
This section lists the methods available in each class and discusses them in a more organized and formal manner compared to above.
screen_size (get only)
__init__(self, screen_dimensions)
Creates an instance of GameScreen. DO NOT instantiate images/surfaces here. Put instantiation code in setup() method.
screen_dimensions is an iterable with at least two elements. GameScreen expects that the first element of screen_dimensions is the width while the second one is the height.
setup(self)
Instantiate images/surfaces here. This method is invoked before the game loop starts.
draw_screen(self, window)
Here is where you put the code that will draw the screen. By itself, this should only be concerned as to how the screen should look like for this iteration of the game loop and not on how the screen came to be this way; encapsulate that elsewhere, in a Model, prefferrably.
This class can be viewed as a game's controller. This allows you to set-up and specify what happens in a game loop.
config (get only)
The current configuration of the game, as a GameConfig object.
game_screen (get only)
The screen to which this GameLoopEvents is attached (in MVC parlance, the view to which this controller is attached).
event_handlers (get only)
A dictionary mapping PyGame events to specific functions which get invoked when the specified event is triggered.
key_handlers (get only)
A dictionary mapping key stroke values to specific functions which get invoked when the given key is pressed.
stop_loop(self, event)
By default, this is the function that gets invoked in response to event pygame.QUIT. This simply breaks the game loop so that a pygame.quit() line gets executed. You may override this if you need specific behavior upon quitting (like telling the player "Nooooo!!! Your game needs you!!!"). Make sure to invoke the parent's stop_loop though so that you are sure that the loop gets broken.
add_event_handler(self, event, handler)
Maps a given PyGame event to a function. After the invocation, whenever the given event arises, the mapped function is called.
event should be taken from pygame.event.get()
handler is a function which takes in arguments depending on the event to be handled.
Note that it is recommended that you place your calls to add_event_handler in...
attach_event_handlers(self)
Really, just call them here. This method is, in turn, called at...
loop_setup(self)
As noted above, you should override this method to set-up the objects and variables you will need in the loop. However, it is important that you always call the loop_setup methods of your super classes. GameLoopEvents, for one, instantiates its own stuff here. Look-up a bit for an example.