Pygtails Library

A simple wrapper around pygame.

Game implements engine functionality. Subclass to build games. GameObject A simple class to provide a more intuitive approach to gamedev.

Game

class pygtails.Game(resolution, title, flags=0, depth=0)

A class that handles pygame events, input, and mouse-collision.

resolution is a 2-tuple of integers that specify the width and height of the screen.

title is a string used as the title of the window.

flags is an integer flag representing the different controls over the display mode that are active. For a full list of the different flags, see Pygame Display Mode Flags. For more information on how flags work, see the Flags tutorial.

Public Methods:

main, quit, on_focus, on_key_down, on_key_up, on_mouse_move,

on_mouse_up, on_mouse_down, on_resize, update, add_object,

destroy_object, key_is_pressed

Instance variables:

screen

add_object(other)

Add a GameObject other to the Game and return its id.

destroy_object(_id)

Destroys the object with the given id from the game.

Note: Does not “undraw” the object. This must be done manually (for now)

key_is_pressed(key)

Return True if a key is pressed, False if not.

key is pygame keycode. For a full list of keycodes, see Pygame Keycodes.

main()

The main loop. Call this to run the game.

on_focus(event)

This method is called whenever the window loses or gains focus.

event is a pygame ACTIVEEVENT event. It contains the event attributes gain and state.

event.gain is an integer. It has a value of 1 when the window comes into focus or when the mouse enters the window. It has a value of 0 when the window goes out of focus or when the mouse leaves the window.

event.state is an integer. It has a value of 1 when the mouse exits or leaves the window. It has a value of 2 when the window gains or loses focus.

This method is not predefined.

on_key_down(event)

This method is called whenever a key is pressed.

event is a pygame KEYDOWN event. It contains the event attributes unicode, key, and mod.

event.unicode is the unicode representation of the key being pressed.

event.key is a pygame keycode representing the key being pressed. For a full list key constants, see Pygame Keycodes.

event.mod is a pygame key mod flag representing the “modulating” keys (shift, ctrl, alt, etc.) being pressed when the current key was pressed. For a list of these flags, see Pygame Key Mod Flags.

This method is not predefined.

on_key_up(event)

This method is called whenever a key is released.

event is a pygame KEYUP event. It contains the event attributes key and mod.

event.key is a pygame keycode representing the key being released. For a full list key constants, see Pygame Keycodes.

event.mod is a pygame key mod flag representing the “modulating” keys (shift, ctrl, alt, etc.) pressed when the current key was released. For a full list of these flags, see Pygame Key Mod Flags.

This method is not predefined.

on_mouse_down(event)

This method is called whenever a mouse button is pressed.

event is a pygame MOUSEBUTTONDOWN event. It contains the event attributes pos and button.

event.pos is a 2-tuple of integers representing the x and y coordinates of the mouse when it was released.

event.button is an integer representing the button being pressed. 1 represents the left mouse button, 2 represents the middle mouse button, and 3 represents the right mouse button.

This method is predefined to implement the GameObject.on_mouse_down method and to update internal data bout whether or not an object is clicked.

To redefine this method while keeping the implementation, call super().on_mouse_up(event) at the top of your function.

on_mouse_move(event)

This method is called whenever the mouse is moved.

event is a pygame MOUSEMOTION event. It contains the event attributes pos, rel, and buttons.

event.pos is a 2-tuple of integers representing the x and y coordinates of the mouse.

event.rel is a 2-tuple of integers representing the change in x and y coordinates since the last time this function was called.

event.buttons is a 3-tuple of integers representing the amount of mouse buttons being pressed. Index 0 represents the left mouse button, 1 represents the middle mouse button, 2 represents the right mouse button. If the mouse button is down, the value is 1, 0 if it’s up.

This method is predefined to implement the on_mouse_[enter, exit, drag] functions.

If you aren’t satisfied with the implementation, feel free to redefine it. If you want to keep the implementation but also add additional functionality call super().on_mouse_move(event) when you’re redefining the function.

on_mouse_up(event)

This method is called whenever a mouse button is released.

event is a pygame MOUSEBUTTONUP event. It contains the event attributes pos and button.

event.pos is a 2-tuple of integers representing the x and y coordinates of the mouse when it was released.

event.button is an integer representing the button being released. 1 represents the left mouse button, 2 represents the middle mouse button, and 3 represents the right mouse button.

This method is predefined to implement the GameObject.on_mouse_up method and to update internal data about whether or not an object is clicked.

To redefine this method while keeping the implementation call super().on_mouse_up(event) at the top of your function.

on_resize(event)

This method is called whenever the window is resized.

event is a pygame VIDEORESIZE event. it contains the event attributes size, w, and h.

event.size is a 2-tuple of integers representing the width and height of the screen.

event.w is an integer representing the width of the screen.

event.h is an integer representing the height of the screen.

This method is not predefined.

quit(event)

The method called when the exit button is pressed.

event is a pygame QUIT event. It has no event attributes.

This method is predefined as:

pygame.quit()
sys.exit()

Redefine it if you need more control.

screen

The pygame Surface used to draw and blit images to the screen.

update()

This method is called every frame.

This method is not predefined.

GameObject

class pygtails.GameObject(game)

A simple class to (hopefully) make pygame more intuitive.

game is the pygame.Game that this GameObject will be added to.

Intializing a GameObject modifies internal data in the Game it’s instantiated by.

Public Methods:

update, on_mouse_enter, on_mouse_exit, on_mouse_stay, on_mouse_down,

on_mouse_up, on_mouse_drag, move

Instance Variables:

game, ID

ID

An integer that represents this object’s id.

destroy()

Deletes this object from the game world.

game

The pygtails.Game object that this object is a part of.

on_mouse_down(event)

This method is called when the mouse is pressed inside this object.

event is a pygame MOUSEBUTTONDOWN event. It contains the event attributes pos and button.

event.pos is a 2-tuple of integers representing the x and y coordinates of the mouse when it was released.

event.button is an integer representing the button being pressed. 1 represents the left mouse button, 2 represents the middle mouse button, and 3 represents the right mouse button.

This method is not predefined.

on_mouse_drag(event)

This method is called each frame this object is dragged by the mouse.

event is a pygame MOUSEMOTION event. It contains the event attributes pos, rel, and buttons.

event.pos is a 2-tuple of integers representing the x and y coordinates of the mouse.

event.rel is a 2-tuple of integers representing the change in x and y coordinates since the last time this function was called.

event.buttons is a 3-tuple of integers representing the amount of mouse buttons being pressed. Index 0 represents the left mouse button, 1 represents the middle mouse button, 2 represents the right mouse button. If the mouse button is down, the value is 1, 0 if it’s up.

This method is not predefined.

on_mouse_enter(event)

This method is called whenever the mouse enters this object.

event is a pygame MOUSEMOTION event. It contains the event attributes pos, rel, and buttons.

event.pos is a 2-tuple of integers representing the x and y coordinates of the mouse.

event.rel is a 2-tuple of integers representing the change in x and y coordinates since the last time this function was called.

event.buttons is a 3-tuple of integers representing the amount of mouse buttons being pressed. Index 0 represents the left mouse button, 1 represents the middle mouse button, 2 represents the right mouse button. If the mouse button is down, the value is 1, 0 if it’s up.

This method is not predefined.

on_mouse_exit(event)

This method is called whenever the mouse exits this object.

event is a pygame MOUSEMOTION event. It contains the event attributes pos, rel, and buttons.

event.pos is a 2-tuple of integers representing the x and y coordinates of the mouse.

event.rel is a 2-tuple of integers representing the change in x and y coordinates since the last time this function was called.

event.buttons is a 3-tuple of integers representing the amount of mouse buttons being pressed. Index 0 represents the left mouse button, 1 represents the middle mouse button, 2 represents the right mouse button. If the mouse button is down, the value is 1, 0 if it’s up.

This method is not predefined.

on_mouse_stay(event)

This method is called each frame the mouse is within this object.

event is a pygame MOUSEMOTION event. It contains the event attributes pos, rel, and buttons.

event.pos is a 2-tuple of integers representing the x and y coordinates of the mouse.

event.rel is a 2-tuple of integers representing the change in x and y coordinates since the last time this function was called.

event.buttons is a 3-tuple of integers representing the amount of mouse buttons being pressed. Index 0 represents the left mouse button, 1 represents the middle mouse button, 2 represents the right mouse button. If the mouse button is down, the value is 1, 0 if it’s up.

This method is not predefined.

on_mouse_up(event)

This method is called on mouse up if this object is clicked.

event is a pygame MOUSEBUTTONUP event. It contains the event attributes pos and button.

event.pos is a 2-tuple of integers representing the x and y coordinates of the mouse when it was released.

event.button is an integer representing the button being released. 1 represents the left mouse button, 2 represents the middle mouse button, and 3 represents the right mouse button.

This method is not predefined.

update()

This method is called every frame.

This method is not predefined.

Circle

class pygtails.Circle(game, corner, radius)

A GameObject with a circular “hitmask”.

game is the Game this object is a part of.

corner is a 2-tuple of integers representing the x and y coordinates of the upper-left corner of the bounding square of circle.

radius is a numeric value representing the radius of the circle.

Initializing a Circle will modify internal data in the Game it’s instantiated with.

Public Methods:

update, on_mouse_enter, on_mouse_exit, on_mouse_stay, on_mouse_down,

on_mouse_up, on_mouse_drag, move

Instance Variables:

game, ID, center, corner, radius

center

A 2-tuple of integers representing the center of the circle.

Setting this will change the center and corner attributes.

corner

A 2-tuple of integers representing the center of the circle.

Setting this will change the corner and center attributes.

radius

An integer representing the radius of the circle.

Setting this will change the radius and center attributes.

Rectangle

class pygtails.Rectangle(game, corner, width, height)

A GameObject with a rectangular “hitmask”.

game is the Game this object is a part of.

corner is a 2-tuple of integers representing the x and y coordinates of the upper-left corner of the rectangle.

width is an integer representing the width of the rectangle.

height is an integer representing the height of the rectangle.

Initializing a Rectangle will modify internal data in the Game it’s instantiated with.

Public Methods:

update, on_mouse_enter, on_mouse_exit, on_mouse_stay, on_mouse_down,

on_mouse_up, on_mouse_drag, move

Instance Variables:

game, ID, corner, width, height

corner

The upper left corner of the rectangle.

A 2-tuple of integers that represent the x and y coordinates of the upper-left corner of the rectangle.

This attribute is mutable.

corners

A tuple of all of the corners of the rectangle.

A 2-dimensional tuple, where the inner tuples are 2-tuples of integers representing the x and y coordinates of the different corners of the rectangle.

The order that the points appear are top-left, top-right, bottom-right, bottom-left.

This attribute is immutable.

height

An integer that represents the height of the rectangle.

This attribute is mutable.

width

An integer that represents the width of the rectangle.

This attribute is mutable.