Beginning Python Games Development With Pygame (2015)

APPENDIX A

Game Object Reference

This appendix documents some of the most fundamental classes in the Game Objects library that provide a toolbox for creating 2D and 3D games. For up-to-date information regarding Game Objects, see https://github.com/PythonProgramming/Beginning-Game-Development-with-Python-and-Pygame.

Importing

The Game Objects library consists of a number of submodules that can be imported separately. Generally it is best to import only the classes you need using the from <module> import <object> syntax. For example, this line imports the Color class:

from gameobjects.color import Color

Occasionally there are helper functions from the submodules that you may also want to use. In this case you can use from <module> import * to import everything into your namespace. For example, the following line will import everything in the gameobjects.vector3class:

from gameobjects.vector3 import *

Contributing

The Game Objects library is an open source project, which means that any programmer may contribute. You are encouraged to submit any bug fixes you find, or classes that you think may be useful additions to the library.

gameobjects.color.Color

Color objects represent a color with an alpha value. The components are stored in the range zero to one, as used by OpenGL, but you can convert to integer RGBA format with the rgba8 attribute or as_tuple method. Color objects support the basic mathematical operators; multiply, divide, add, and subtract. You can also multiply or divide colors by a scalar value (e.g., an integer or float), but adding or subtracting a scalar will throw a TypeError exception.

Constructor

The gameobjects.color constructor takes the red, green, and blue components and an optional alpha component, in the range zero to one. The components can also be given as a sequence of three or four values. If a color is constructed without any parameters, it will default to black.

Attributes

The components can be retrieved and set with the r, g, b, and a attributes (see Table A-1). The rgba8 and rgb8 (read-only) attributes can be used to retrieve the component as a tuple of integers in the 0 to 255 range.

Table A-1. gameobjects.color Attributes

Attribute	Purpose
r	Red component in the zero to one range
g	Green component in the zero to one range
b	Blue component in the zero to one range
a	Alpha component in the zero to one range
rgba8	Tuple of (red, green, blue, alpha) components, in the 0 to 255 range (compatible with Pygame’s draw functions)
rgb8	Tuple of (red, green, blue) components, in the 0 to 255 range

Methods

Color objects support the methods shown in Table A-2.

Table A-2. Color Methods

Method Name	Explanation
copy()	Returns a copy of the color
as_tuple()	Returns a copy of the color as a tuple of its components
as_tuple_rgb()	Returns a copy of the color as a tuple of its red, green, and blue components
as_tuple_rgba()	Identical to as_tuple
as_html()	Returns a string containing the color in HTML format
saturate()	Forces all components to be in the range zero to one
get_saturate()	Returns a copy of the color where all the components have been saturated to the range 0–1
invert()	Inverts the color (sets each component to one minus itself)
mul_alpha()	Multiplies the red, green, and blue components by the alpha component

Class Methods

The gameobjects.color class contains a number of class methods that offer alternative ways of creating new color objects (see Table A-3).

Table A-3. Color Class Methods

Method Name	Explanation
black()	Returns a color object representing black.
white()	Returns a color object representing full white.
from_rgba8(r, g, b, a)	Creates a color object from color components in the range 0–255.
from_html(col_str)	Creates a color object from a color encoded in HTML format.
gray (level)	Creates a gray color object; level is a value in the zero to one range.
from_palette(color_name)	Creates a named color from an internal palette, for example, red, ivory, aquamarine, etc. See the online documentation for a full list.

gameobjects.matrix44.Matrix44

The Matrix44 class stores a 4 x 4 matrix representing a 3D transform.

Constructor

If no parameters are given, the matrix is initialized to identity. If one parameter is given, it should be a sequence (e.g., a list) with the 16 components of the matrix. If four parameters are given, they should be four sequences of up to four values. Missing values in each row are padded out with values from the identity matrix (so you can use Vector3s or tuples of three values).

Attributes

The attributes of a matrix44 object (see Table A-4) represent the rows of the matrix. You can only retrieve or set the contents of these attributes as a whole—that is, you can’t set parts of the row individually. If you need to access the components of the matrix as individual values, use the index ([]) operator of the matrix44 object.

Table A-4. gameobjects.matrix44.Matrix44 Attributes

Attribute	Explanation
x_axis	The x axis of the matrix
right	Alias for the x axis
y_axis	The y axis of the matrix
up	Alias for the y axis
z_axis	The z axis of the matrix
forward	Alias for the z axis
translate	The translation part of the matrix

Methods

Matrix objects contain a large number of methods to manipulate the components of the matrix and use it to transform points (see Table A-5).

Table A-5. Matrix44 Attributes

Method Name	Explanation
to_opengl()	Returns a list of the matrix components, compatible with OpenGL.
set(row1, row2, row3, row4)	Sets the four rows of the matrix.
get_row(row_no)	Retrieves a row of the matrix as a tuple of four values; row_no is the row index (0, 1, 2, or 3).
fast_mul(rhs)	Multiplies the matrix by another matrix. This is a little quicker than the *= operator, but can only be used with matrices that contain only rotate, scale, or translation.
copy()	Returns a copy of this matrix.
components()	Returns an iterator of the 16 matrix components.
transposed_components()	Returns an iterator of the 16 matrix components, in transposed order.
rows()	Returns an iterator of the matrix rows as tuples of four values.
columns()	Returns an iterator of the matrix columns as tuples of four values.
get_row_vec3(row_no)	Retrieves a row as a Vector3 object.
get_column(col_no)	Retrieves a column as a tuple of four values.
set_row(row_no, row)	Sets the contents of a row; row_no is the index of the row to set, and row is a sequence of up to four values to set it to.
set_column(col_no, col)	Sets the contents of a column; col_no is the index of the column and row is a sequence of up to four values to set it to.
transform_vec3(v)	Transforms a Vector3 object (v) with this matrix, and returns the result as another Vector3.
transform(v)	Transforms a vector and returns the result as a tuple.
transform_sequence(points)	Transforms a sequence of points and returns the result as a list of tuples.
rotate(v)	Transforms a point with the matrix, but ignores the translation part of the matrix.
transpose()	Swaps the rows and columns of the matrix.
get_transpose()	Returns a transposed copy of the matrix.
get_inverse_rot_trans()	Returns the inverse of a matrix with only rotation and translation.
get_inverse()	Returns the inverse of this matrix.
invert()	Inverts this matrix (in place).
move(forward, right, up)	Adds offsets to the translation based on its heading. The parameters are all optional and should be sequences of three values.

Class Methods

The Matrix44 class contains a number of class methods to create basic transform matrices (see Table A-6).

Table A-6. Matrix44 Class Methods

Class Method Name	Explanation
from_iter(iterable)	Creates a matrix from an iterable (anything that can work in a for loop) of 16 values.
clone(m)	Creates a copy of matrix m.
identity()	Creates an identity matrix.
scale(x, y, z)	Creates a scale matrix. If the y and z scales are omitted, a uniform scale matrix of x is returned.
translation(x, y, z)	Creates a translation matrix to (x, y, z).
x_rotation(angle)	Creates a rotation matrix of angle radians about the x axis.
y_rotation(angle)	Creates a rotation matrix of angle radians about the y axis.
z_rotation(angle)	Creates a rotation matrix of angle radians about the z axis.
rotation_about_axis(axis, angle)	Creates a rotation matrix about an axis. The axis parameter can be any sequence of three values; the angle parameter should be in radians.
xyz_rotation(x, y, z)	Creates a matrix that has the combined effect of rotating around all three axes.

gameobjects.vector2.Vector2

The Vector2 class represents a two-dimensional vector and can be used to store headings and positions in a 2D game. The components of a Vector2 object can be accessed via the x and y attributes, or through the index operator ([]). Vector2 objects support the mathematical operators.

Constructor

The constructor for Vector2 objects takes either two values for the x and y components of the vector, or a sequence of two values. If no parameters are given, the vector will default to (0, 0).

Attributes

Table A-7 lists the attributes for Vector2 objects.

Table A-7. Vector2 Attributes

Attribute	Explanation
x	The x component of the vector.
y	The y component of the vector.
length	The length of the vector. This attribute can also be set to change the length of the vector.

Methods

Table A-8 lists the methods for Vector2 objects.

Table A-8. Vector2 Methods

Method Name	Explanation
copy()	Returns a copy of this vector.
get_length()	Returns the length of this vector.
get_magnitude()	Returns the magnitude (same as length) of this vector.
normalize()	Normalizes this vector, so that it has a length of 1. Also returns the vector.
get_normalized()	Returns a normalized copy of the vector.
get_distance:to()	Returns the distance from this vector to a point.

Class Methods

The Vector2 class has a number of methods to construct new Vector2 objects (see Table A-9).

Table A-9. Vector2 Class Methods

Class Method Name	Explanation
from_iter(iterable)	Creates a Vector2 object from an iterable of values.
from_points(p1, p2)	Creates a Vector2 object from two points.

gameobjects.vector3.Vector3

The Vector3 class represents a 3D vector, which can be used to store headings and position in three-dimensional space. Vector3 objects are very similar to Vector2 objects but contain an extra attribute, z.

Constructor

The constructor for Vector3 objects takes either three values for the x, y, and z components of the vector, or a sequence of three values. If no parameters are given, the vector will default to (0, 0, 0).

Attributes

Table A-10 lists the attributes for Vector3 objects.

Table A-10. Vector2 Attributes

Attribute	Explanation
x	The x component of the vector.
y	The y component of the vector.
z	The z component of the vector.
length	The length of the vector. This attribute can also be set to change the length of the vector.

Methods

Table A-11 lists the methods for Vector3 objects.

Table A-11. Vector3 Methods

Method Name	Explanation
set(x, y, z)	Sets the components of the vector to the float values.
as_tuple()	Returns the vector as a tuple of three values.
get_length()	Retrieves the length of the vector.
get_magnitude()	Retrieves the magnitude (same as length) of the vector.
set_length()	Sets the length of the vector.
get_distance:to(p)	Retrieves the distance from this vector to a point.
normalize()	Normalizes the vector, so that it has a length of 1. Also returns the vector.
get_normalized()	Returns a normalized copy of the vector.
dot(other)	Returns the dot-product of this vector with another vector.
cross(other)	Returns the cross-product of this vector with another vector.

Class Methods

Table A-12 lists the class methods that can be used to create new Vector3 objects.

Table A-12. Vector3 Class Methods

Class Method Name	Explanation
from_points(p1, p2)	Creates a Vector3 object between two points.
from_iter(iterable)	Creates a Vector3 object from an iterable of three values.