GNU PGE

PGE Python API

class object

object - the class of objects in the 2D world. An object can either be a colour, circle, polygon, spring or text. A text object can not exist in level 0. Objects are drawn from lowest level to highest level. Only objects in level 0 are processed by the physics engine. All other levels are eye candy.

object.velocity (self, vx, vy)

velocity - Pre-condition: an circle or polygon object which is not fixed and exists at level 0. Post-condition: assign the velocity (vx, vy) to this object.

object.accel (self, ax, ay)

accel - Pre-condition: an circle or polygon object which is not fixed and exists at level 0. Post-condition: assign the accel (vx, vy) to this object.

object.fix (self)

fix - Pre-condition: the object is either a circle or polygon which exists in level 0. Post-condition: mark this object as fixed to its initial position.

object.mass (self, m)

mass - Pre-condition: the object is either a circle or polygon which exists in level 0. The object must not be fixed. Post-condition: object is given mass, m.

object.apply_impulse (self, unit_vec, magnitude)

apply_impulse - Pre-condition: the object is either a circle or polygon which exists in level 0. The object must not be fixed. Post-condition: the object is given an impulse along vector, unit_vec, with a, magnitude. unit_vec is a list of two elements [x, y] magnitude is a float.

object.on_collision_with (self, another, p)

on_collision_with - Pre-condition: the object is either a circle or polygon which exists in level 0. Post-condition: when this object collides with any object in the list, another, then function, p, is called. The parameter, another, is a list of objects. p must be a function which receives two parameters an object and an event.

object.on_collision (self, p)

on_collision - Pre-condition: the object is either a circle or polygon which exists in level 0. Post-condition: when this object collides call function, p. p is a function with two parameters, o and e. o is this object. e is the event.

object.rm (self)

rm - Pre-condition: the object can be a circle, polygon or text at any level. Post-condition: the object is removed.

object.get_param (self)

get_param - Pre-condition: self is a polygon or circle object. Post-condition: returns user data given to this object.

object.set_param (self, value)

set_param - Pre-condition: self is a polygon or circle object. Post-condition: assigns value as the user data to this object.

object.set_width (self, value)

set_width - Pre-condition: self is a polygon or circle object. Post-confition: assigns an overall width value to an object. This value is not used by the physics engine. It is only present for user convenience.

object.get_width (self)

get_width - Pre-condition: self is a polygon or circle object which has had a user defined width set. Post-condition: returns the overall width value for this object.

object.get_mass (self)

get_mass - Pre-condition: self is a polygon or circle object. Post-condition: return the mass of this object.

object.get_colour (self)

get_colour - Pre-condition: self is a polygon or circle object. Post-condition: return the colour of this object.

object.set_colour (self, c)

set_colour - Pre-condition: self is a polygon or circle object. Post-condition: this object will be displayed in colour, c.

object.get_unit_coord (self)

get_unit_coord - Pre-condition: object must be a circle. Post-condition: return a list [x, y] representing the coordinate center of this object. Each x, y value will be between 0.0 and 1.0.

object.get_xpos (self)

get_xpos - Pre-condition: object must be a circle or polygon. Post-condition: return the x position of this object. The value will be between 0.0 and 1.0.

object.get_ypos (self)

get_ypos - Pre-condition: object must be a circle or polygon. Post-condition: return the y position of this object. The value will be between 0.0 and 1.0.

object.get_xvel (self)

get_xvel - Pre-condition: object must be a circle or polygon. Post-condition: return the x velocity of this object.

object.get_yvel (self)

get_yvel - Pre-condition: object must be a circle or polygon. Post-condition: return the y velocity of this object.

object.get_xaccel (self)

get_xaccel - Pre-condition: object must be a circle or polygon. Post-condition: return the x accel of this object.

object.get_yaccel (self)

get_yaccel - Pre-condition: object must be a circle or polygon. Post-condition: return the y accel of this object.

object.put_xvel (self, f)

put_xvel - Pre-condition: object must be a circle or polygon. Post-condition: assigns a float, f, as the x velocity of this object.

object.put_yvel (self, f)

put_yvel - Pre-condition: object must be a circle or polygon. Post-condition: assigns a float, f, as the y velocity of this object.

object.put_xaccel (self, f)

put_xaccel - Pre-condition: object must be a circle or polygon. Post-condition: assigns a float, f, as the x acceleration of this object.

object.put_yaccel (self, f)

put_xaccel - Pre-condition: object must be a circle or polygon. Post-condition: assigns a float, f, as the y acceleration of this object.

object.moving_towards (self, x, y)

moving_towards - Pre-condition: object must be a non fixed circle or polygon. Post-condition: returns True if this object is moving towards point [x, y]. x and y must be in the range of 0.0 and 1.0.

object.draw (self, c, w)

draw - draw a spring using colour, c, and a width, w. It is drawn under the objects it connects. The spring object is returned.

object.end (self, c)

end - draw the objects at the end of the spring with colour, c, when the object comes to rest.

object.mid (self, c)

mid - draw a debugging frame when the spring reaches its rest point. The objects connected by the spring are drawn with colour, c.

object.when (self, l, p)

when - when spring reaches a length, l, call function, p. p is a function with two parameters, o and e. o is this object. e is the event.

object.rgb (r, g, b)

rgb - Pre-condition: None. Post-condition: create a colour object from the red, green, blue triple. The r, g, b, values must between 0.0 and 1.0.

object.white ()

white - Pre-condition: None. Post-condition: return a colour object representing the colour white.

object.text (x, y, s, c, size, level)

text - place text string, s, at position [x, y] in colour, c. The size will be in font size and placed in the foreground or background depending upon level. You are not allowed to place text in level zero.

object.box (x, y, w, h, c, level = 0)

box - create a box at position, [x, y]. x and y have the range 0.0 to 1.0. w and h are the width and height and are in the range 0.0 to 1.0. c is a colour object. level is optional, if it is not present it defaults to zero. Otherwise the level determines whether it exists in the foreground or background.

object.poly3 (x0, y0, x1, y1, x2, y2, c, level = 0)

poly3 - create a triangle at position, [x0, y0], [x1, y1], [x2, y2] all values have the range 0.0 to 1.0. c is a colour object. level is optional, if it is not present it defaults to zero. Otherwise the level determines whether it exists in the foreground or background.

object.poly4 (x0, y0, x1, y1, x2, y2, x3, y3, c, level = 0)

poly4 - create a polygon of four vertices at position, [x0, y0], [x1, y1], [x2, y2], [x3, y3] all values have the range 0.0 to 1.0. c is a colour object. level is optional, if it is not present it defaults to zero. Otherwise the level determines whether it exists in the foreground or background. The coordinates must either be given in clockwise or anticlockwise order.

object.spring (ob1, ob2, k, d, l = None)

spring - place a spring of at rest length, l, and Hook's value of, k, between object ob1 and object ob2. The objects, ob1, and, ob2, must be either a circle or a polygon. A spring only exists at level 0 (in the physics engine). If, l, is omitted then it is assummed that the spring starts at rest between, ob1, and, ob2.

object.circle (x, y, r, c, level = 0)

circle - place a circle at coordinate (x, y) The circle has a radius, r, and is filled with colour, c. If the level == 0 it is placed into the physics engine. A level < 0 is placed into the background. A level > 0 is placed into the foreground.

class event

the event class is used by the user through call back functions. In particular the user can find out the collision_between two objects, cancel a timer event or query whether a timer event was cancelled.

event.collision_between (self)

collision_between - Pre-condition: event object must a collision event. Post-condition: returns a list of two objects which are in collision.

event.cancel (self)

cancel - Pre-condition: event must be a timer event. Post-condition: timer event is cancelled.

event.was_cancelled (self)

was_cancelled - Pre-condition: event must be a timer event. Post-condition: returns True if this event was cancelled.

event.get_timer_id (self)

get_timer_id - Pre-condition: event must be a timer event Post-condition: timer id is returned.

event.at_time (t, p)

at_time - informs the physics engine to create a call to function, p, at time, t, in the future. It returns a integer reference for the timed function. Pre-condition: t is a time seconds (float) in the future. p, is a function which takes a single parameter the event. Post-condition: function p is placed into the timer list and a timer id (integer) is returned.

event.at_cancel (i)

at_cancel - Pre-condition: the integer reference for the timed function. Post-condition: cancel the timed function.

event.record ()

record - record the game. A file output.raw will be created which can be post processed by pgeplayback. Pre-condition: None. Post-condition: the record flag is set and the game will be recorded.

event.gravity (value=-9.81)

gravity - Pre-condition: None. Post-condition: turn on pge world gravity, if parameter is missing the default of 9.81ms^2 is used.

event.get_font (size)

get_font - Pre-condition: None. Post-condition: return the font corresponding to size pixels height.

event.register_handler (function, pyeventlist)

register_handler - Pre-condition: None. Post-condition: call, function, if any event in pyeventlist occurs.

event.deregister_handler (pyeventlist)

deregister_handler - Pre-condition: None. Post-condition: remove the handlers for pyeventlist.

event.runpy (t=-1)

runpy - Pre-condition: all objects have been initialised correctly in the 2D world. Post-condition: runs pge for time, t, seconds and also process the pygame events the objects appear in the Pygame screen.

event.runbatch (t)

runbatch - Pre-condition: all objects have been initialised correctly in the 2D world. Post-condition: runs pge for time, t. If t < 0.0 then simulate for 30.0 seconds max. Nothing is rendered visually, but the graphics can be directed to a file using the record function.

event.display_set_mode (r)

display_set_mode - Pre-condition: this must be called before pge.run. The parameter is a list [x, y]. Current limitation the y parameter is overwritten by the x value. Post-condition: the resolution will be used when pge.run. is called.

event.display_fullscreen (b)

display_fullscreen - Pre-condition: this must be called before pge.run. Post-condition: configure the Pygame to use fullscreen.

event.fps (f)

fps - Pre-condition: this must be called before pge.run. Post-condition: the game engine will render the world at, f, frames per second.

event.get_frame_no ()

get_frame_no - return the current frame number.

event.run (t=-1)

run - Pre-condition: all objects and any screen resolution must be configured. Post-condition: runs pge for time, t, seconds and also process the pygame events

event.batch ()

batch - Pre-condition: None. Post-condition: configures pge to run in batch mode, without any display and without any pygame. No input events are allowed in this mode.

event.interactive ()

interactive - Pre-condition: None. Post-condition: configures pge to use pygame and it allows interactivity from the python pygame event queue.

event.finish_record ()

finish_record - Pre-condition: record must have been called. Post-condition: finish recording the game and flush the record file.