This page is the full documentation of gamebox.py, extracted from its docstrings. Looking for a quick-start guide instead? See the gamebox sumamry overview.

1 Name

gamebox

2 Description

This code is the original work of Luther Tychonievich, who releases it into the public domain.

As a courtesy, Luther would appreciate it if you acknowledged him in any work that benefited from this code.

3 Classes

3.1 Camera

A camera defines what is visible. It has a width, height, full screen status, and can be moved. Moving a camera changes what is visible.

3.1.1 Methods defined here:

3.1.1.1 clear

Usage: camera.clear(color)

Erases the screen by filling it with the given color

3.1.1.2 display

Usage: camera.display()

Causes what has been drawn recently by calls to draw(…) to be displayed on the screen

3.1.1.3 draw

Usage: camera.draw(thing, *args)

camera.draw(box) draws the provided SpriteBox object

camera.draw(image, x, y) draws the provided image centered at the provided coordinates

camera.draw("Hi", 12, "red", x, y) draws the text Hi in a red 12-point font at x,y

3.1.1.4 move

Usage: camera.move(x, y=None)

camera.move(3, -7) moves the screen’s center to be 3 more pixels to the right and 7 more up

3.1.2 Attributes defined here

3.1.2.1 Attributes you may set

The following attributes refer to the center of the viewable area:

  • center, which equals (x, y)
  • x
  • y

The following attributes refer to the edge of the viewable area:

  • left
  • right
  • top
  • bottom

The following attributes refer to a corner of the viewable area:

  • topleft
  • topright
  • bottomleft
  • bottomright

3.1.2.2 Attributes you may access but not set

The following refer to the size of the viewable area

  • width
  • height
  • size, which equals (width, height)

The following refer to the mouse cursor

  • mousex
  • mousey
  • mouse, which equals (mousex, mousey)
  • mouseclick, which is a Boolean value

3.1.2.3 User-defined attributes

You can add as many other attributes as you want, by (e.g.) saying camera.number_of_coins_found = 5.

3.2 SpriteBox

Intended to represent a sprite (i.e., an image that can be drawn as part of a larger view) and the box that contains it. Has various collision and movement methods built in.

SpriteBoxes are created using the functions from_image, from_text, or from_color.

3.2.1 Methods defined here:

3.2.1.1 bottom_touches

Usage: box.bottom_touches(other, padding=0, padding2=None)

b1.bottom_touches(b2) returns True if both b1.touches(b2) and b1’s bottom edge is the one causing the overlap. See touches for a description of the optional padding arguments.

3.2.1.2 contains

Usage: box.contains(x, y=None)

checks if the given point is inside this SpriteBox’s bounds or not

3.2.1.3 copy

Usage: box.copy()

Make a new SpriteBox just like this one and in the same location

3.2.1.4 copy_at

Usage: box.copy_at(newx, newy)

Make a new SpriteBox just like this one but at the given location instead of here

3.2.1.5 draw

Usage: box.draw(surface)

b1.draw(camera) is the same as saying camera.draw(b1)

b1.draw(image) draws a copy of b1 on the image proivided

3.2.1.6 flip

Usage: box.flip()

mirrors the SpriteBox left-to-right.

Mirroring top-to-bottom can be accomplished by

b1.rotate(180)
b1.flip()

3.2.1.7 full_size

Usage: box.full_size()

change size of this SpriteBox to be the original size of the source image

3.2.1.8 left_touches

Usage: box.left_touches(other, padding=0, padding2=None)

b1.left_touches(b2) returns True if both b1.touches(b2) and b1’s left edge is the one causing the overlap. See touches for a description of the optional padding arguments.

3.2.1.9 move

Usage: box.move(x, y=None)

change position by the given amount in x and y. If only x given, assumed to be a point [x, y]

3.2.1.10 move_both_to_stop_overlapping

Usage: box.move_both_to_stop_overlapping(other, padding=0, padding2=None)

b1.move_both_to_stop_overlapping(b2) changes both b1 and b2’s positions so that they no longer overlap. See touches for a description of the optional padding arguments.

3.2.1.11 move_speed

Usage: box.move_speed()

change position by the current speed field of the SpriteBox object

3.2.1.12 move_to_stop_overlapping

Usage: box.move_to_stop_overlapping(other, padding=0, padding2=None)

b1.move_to_stop_overlapping(b2) makes the minimal change to b1’s position necessary so that they no longer overlap. See touches for a description of the optional padding arguments.

3.2.1.13 overlap

Usage: box.overlap( other, padding=0, padding2=None)

b1.overlap(b1) returns a list of 2 values such that self.move(result) will cause them to not overlap Returns [0, 0] if there is no overlap (i.e., if b1.touches(b2) returns False).

b1.overlap(b2, 5) adds a 5-pixel padding to b1 before computing the overlap. b1.overlap(b2, 5, 10) adds a 5-pixel padding in x and a 10-pixel padding in y before computing the overlap.

3.2.1.14 right_touches

Usage: box.right_touches(other, padding=0, padding2=None)

b1.right_touches(b2) returns True if both b1.touches(b2) and b1’s right edge is the one causing the overlap. See touches for a description of the optional padding arguments.

3.2.1.15 rotate

Usage: box.rotate(angle)

Rotates the SpriteBox by the given angle (in degrees).

3.2.1.16 scale_by

Usage: box.scale_by(multiplier)

Change the size of this SpriteBox by the given factor. b1.scale_by(1) does nothing; b1.scale_by(0.4) makes b1 40% of its original width and height.

3.2.1.17 top_touches

Usage: box.top_touches(other, padding=0, padding2=None)

b1.top_touches(b2) returns True if both b1.touches(b2) and b1’s top edge is the one causing the overlap. See touches for a description of the optional padding arguments.

3.2.1.18 touches

Usage: box.touches(other, padding=0, padding2=None)

b1.touches(b1) returns True if the two SpriteBoxes overlap, False if they do not. b1.touches(b2, 5) adds a 5-pixel padding to b1 before computing the touch. b1.touches(b2, 5, 10) adds a 5-pixel padding in x and a 10-pixel padding in y before computing the touch.

3.2.2 Attributes defined here

3.2.2.1 Attributes you may access and set

The following attributes refer to the center of the box:

  • center, which equals (x, y)
  • x
  • y

The following attributes refer to the edge of the box:

  • left
  • right
  • top
  • bottom

The following attributes refer to a corner of the box:

  • topleft
  • topright
  • bottomleft
  • bottomright

The following refer to the size of the box:

  • width – setting this also changes height to keep the same aspect ratio.
  • height – setting this also changes width to keep the same aspect ratio.
  • size, which equals (width, height)

The following attributes refer to the speed of the box:

  • speed, which equals (speedx, speedy)
  • speedx, also called xspeed
  • speedy, also called yspeed

The following attribute refers to the current look of the box:

3.2.2.2 Attributes you may access but not set

  • rect, a pygame.Rect providing the location and size of the box.

3.2.2.3 Attributes you may set but not access

  • color, replaces the current look of the box with a solid expanse of color

3.2.2.4 User-defined attributes

You can add as many other attributes as you want, by (e.g.) saying box.number_of_coins_found = 5.

4 Functions

4.1 from_color

Usage: from_color(x, y, color, width, height)

Creates a SpriteBox object at the given location with the given color, width, and height.

4.2 from_image

Usage: from_image(x, y, filename_or_url)

Creates a SpriteBox object at the given location from the provided filename or url.

4.3 from_text

Usage: from_text(x, y, text, fontsize, color, bold=False, italic=False)

Creates a SpriteBox object at the given location with the given text as its content.

4.4 keys_loop

Usage: keys_loop(callback)

Requests that pygame call the provided function each time a key is pressed.

  • callback: a function that accepts the key pressed
def onPress(key):
  if pygame.K_DOWN == key:
      print 'down arrow pressed'
  if pygame.K_a in keys:
      print 'A key pressed'
  camera.draw(box)
  camera.display()

gamebox.keys_loop(onPress)

You can either use keys_loop or use timer_loop, but not both.

4.5 load_sprite_sheet

Usage: load_sprite_sheet(url_or_filename, rows, columns)

Loads a sprite sheet. Assumes the sheet has rows-by-columns evenly-spaced images and returns a list of those images.

4.6 pause

Usage: pause()

Pauses the timer used to run the timer_loop; an error if there is no timer to pause.

4.7 stop_loop

Usage: stop_loop()

Completely quits one timer_loop or keys_loop, usually ending the program.

4.8 timer_loop

Usage: timer_loop(fps, callback)

Requests that pygame call the provided function fps times a second

  • fps: a number between 1 and 1000. Note that numbers above 60 are likely to cause the program to repsond sluggishly.
  • callback: a function that accepts a set of keys pressed since the last tick.
seconds = 0
def tick(keys):
  seconds += 1/30
  if pygame.K_DOWN in keys:
      print 'down arrow pressed'
  if not keys:
      print 'no keys were pressed since the last tick'
  camera.draw(box)
  camera.display()

gamebox.timer_loop(30, tick)

4.9 unpause

Usage: unpause()

Unpauses the timer used to run the timer_loop; an error if there is no timer to unpause.