CoolWorld package

Submodules

CoolWorld.events module

Event management module.

Implements:

class WorldEventManager – generic event management class.
class CoolWorld.events.WorldEventManager(world, name=None, **options)[source]

Bases: CoolWorld.world.WorldItem

Generic event management class.

As a WorldItem subclass, this can be accessed through e.g. self.world.get(“worldeventmanager”) or any other arbitrary name while registering.

Current implementation does nothing as each external lib has its own approach on events handling.

Please, refer to world.WorldItemInterface implementation for more details.

Feel free to subclass this in order to best meet your own specific needs.

CoolWorld.game module

This module gathers all other modules (except tkinter_ui) in one unique common namespace.

This makes it easier to refer to all existing classes through a unique module name.

Example:

from CoolWorld import game
world = game.World2D()
player = game.WorldPlayer2D(world, name="player")
enemy = game.WorldSprite2D(world, name="enemy")
view = game.WorldView(world, name="view")
world.run()

CoolWorld.geometry module

Geometry management module.

Implements:

class WorldAnchorage2D – geometrical anchorage for 2D world.

class WorldAnchorage3D – geometrical anchorage for 3D world.

class WorldArea2D – playground area for 2D world.

class WorldArea3D – playground area for 3D world.

class WorldBoundingBox2D – bounding box for 2D world.

class WorldBoundingBox3D – bounding box for 3D world.

class WorldBoxBase2D – base class for boxes in a 2D world.

class WorldBoxBase3D – base class for boxes in a 3D world.

class WorldPoint2D – geometrical point for 2D world.

class WorldPoint3D – geometrical point for 3D world.

class WorldVector2D – geometrical vector for 2D world.

class WorldVector3D – geometrical vector for 3D world.

class CoolWorld.geometry.WorldAnchorage2D(**options)[source]

Bases: builtins.object

Geometrical anchorage for 2D world.

C = 'c'
CENTER = 'c'
DEFAULT_ANCHOR = 'c'
DEFAULT_ORIGIN = None
DEFAULT_UNIT_VECTOR = (1, 1)
E = 'e'
EAST = 'e'
LEGAL_ANCHORS = ('c', 'e', 'n', 'ne', 'nw', 's', 'se', 'sw', 'w')
N = 'n'
NORTH = 'n'
S = 's'
SOUTH = 's'
W = 'w'
WEST = 'w'
anchor[source]

Anchorage query - read-write attribute.

This must be one of self.LEGAL_ANCHORS e.g. CENTER, EAST, NORTH, etc.

origin[source]

Anchorage point of origin - read-write attribute.

point_type[source]

Preferred point type - read-only attribute.

Current implementation returns WorldPoint2D class type.

This can be redefined in subclasses to fit more specific needs.

unit_vector[source]

Local unit vector - read-write attribute.

vector_type[source]

Preferred vector type - read-only attribute.

Current implementation returns WorldVector2D class type.

This can be redefined in subclasses to fit more specific needs.

class CoolWorld.geometry.WorldAnchorage3D(**options)[source]

Bases: CoolWorld.geometry.WorldAnchorage2D

Geometrical anchorage for 3D world.

DEFAULT_ANCHOR = 'mc'
DEFAULT_ORIGIN = None
DEFAULT_UNIT_VECTOR = (1, 1, 1)
F = 'f'
FRONT = 'f'
LEGAL_ANCHORS = ('fc', 'fe', 'fn', 'fne', 'fnw', 'fs', 'fse', 'fsw', 'fw', 'mc', 'me', 'mn', 'mne', 'mnw', 'ms', 'mse', 'msw', 'mw', 'rc', 're', 'rn', 'rne', 'rnw', 'rs', 'rse', 'rsw', 'rw')
M = 'm'
MIDDLE = 'm'
R = 'r'
REAR = 'r'
point_type[source]

Preferred point type - read-only attribute.

Current implementation returns WorldPoint3D class type.

This can be redefined in subclasses to fit more specific needs.

vector_type[source]

Preferred vector type - read-only attribute.

Current implementation returns WorldVector3D class type.

This can be redefined in subclasses to fit more specific needs.

class CoolWorld.geometry.WorldArea2D(width=0, height=0, **options)[source]

Bases: CoolWorld.geometry.WorldBoxBase2D

Playground area for 2D world.

bounds[source]

Area’s bounding box - read-write attribute.

bounds_type[source]

Preferred bounding box type - read-only attribute.

Current implementation returns WorldBoundingBox2D class type.

This can be redefined in subclasses to fit more specific needs.

default_bounds[source]

Default bounds for bounding box - read-only attribute.

class CoolWorld.geometry.WorldArea3D(width=0, height=0, depth=0, **options)[source]

Bases: CoolWorld.geometry.WorldBoxBase3D, CoolWorld.geometry.WorldArea2D

Playground area for 3D world.

bounds_type[source]

Preferred bounding box type - read-only attribute.

Current implementation returns WorldBoundingBox3D class type.

This can be redefined in subclasses to fit more specific needs.

class CoolWorld.geometry.WorldBoundingBox2D(*points, **options)[source]

Bases: builtins.object

Bounding box for 2D world.

bounding_coords(*points)[source]

Bounding coordinates.

Parameter:
points – variable list of tuple coordinates or point objects.

Returns a 2-tuple of tuple coordinates - minimum and maximum coordinates along with given points.

bounding_corners(*points)[source]

Bounding box corner points.

Parameter:
points – variable list of tuple coordinates or point objects.

returns a tuple list containing all point objects of bounding box’ corners (2D –> 4 corners, 3D –> 8 corners).

bounding_points(*points)[source]

Bounding box’ min/max points.

Parameter:
points – variable list of tuple coordinates or point objects.

returns a 2-tuple list of bounding box’ minimum coords point object and maximum coords point object.

center(query=None)[source]

Build tuple of center dimensions along with query.

Parameter:
query – string of dims (default: None).

If None or omitted, ‘query’ will be replaced by “xy” string of chars.

Any combination of dims is allowed e.g. “x”, “xy”, “yx”, “y”.

Will always return a tuple object, even for only one dimension query e.g. self.center(“x”) –> (self.center_x, ).

center_x[source]

Center of X dimension - read-only attribute.

Current implementation merely returns (self.point1.x + self.point2.x)//2.

center_xy[source]

Tuple center of (X, Y) dimensions - read-only attribute.

Current implementation merely returns a tuple of (self.center_x, self.center_y).

center_y[source]

Center of Y dimension - read-only attribute.

Current implementation merely returns (self.point1.y + self.point2.y)//2.

collided(*points)[source]

Detect if any point is in current bounding box’ bounds.

Parameter:
points – variable list of tuple coordinates or point objects.

Returns True if at least one of listed tuple coordinates (or point object) is into current bounding box’ bounds.

corners[source]

Default bounding box corner points - read-only attribute.

See self.bounding_corners() docstring for more detail.

entered(*points)[source]

Evaluate bounding box’ entered sides.

Parameter:
points – variable list of tuple coordinates or point objects.

Returns a tuple list of any current bounding box side name (‘left’, ‘right’, ‘top’, ‘bottom’) that has been entered by given group of points.

exited(*points)[source]

Evaluate bounding box’ exited sides.

Parameter:
points – variable list of tuple coordinates or point objects.

Returns a tuple list of any current bounding box side name (‘left’, ‘right’, ‘top’, ‘bottom’) that has been exited by given group of points.

height[source]

Bounding box’ height - read-only attribute.

in_bounds(point, *points)[source]

Detect if point is in points’ bounding box bounds.

Parameter:

point – tuple coordinates or point object.

points – variable list of tuple coordinates or point objects.

Returns True if given point is included into the bounding box of listed points (or into current bounding box, if points are omitted).

overlapped(*points)[source]

Detect if current bounding box is overlapped by points.

Parameter:
points – variable list of tuple coordinates or point objects.

Returns True if current bounding box is overlapped in any manner by the bounding box of listed points.

point1[source]

Minimum coordinates point - read-write attribute.

point2[source]

Maximum coordinates point - read-write attribute.

point_type[source]

Preferred point type - read-only attribute.

Current implementation returns WorldPoint2D class type.

This can be redefined in subclasses to fit more specific needs.

reset_bounds(*points)[source]

Reset current bounding box’ bounds.

Parameter:
points – variable list of tuple coordinates or point objects.
size[source]

Bounding box size - read-only attribute.

Returns (width, height) tuple.

to_dict()[source]

Dictionary representation of object attributes.

Returns dict(point1=self.point1, point2=self.point2).

to_flat_tuple()[source]

Flat tuple representation.

All coordinates are linearized into a single tuple.

This converts a ((x1, y1), ..., (xn, yn)) tuple list of tuple coordinates to a single (x1, y1, ..., xn, yn) tuple of flat coordinates.

to_tuple()[source]

Tuple representation of object attributes.

Returns (self.point1, self.point2) tuple.

truth_point(point, *points)[source]

Boolean point representation of bounds detection.

Parameter:

point – tuple coordinates or point object.

points – variable list of tuple coordinates or point objects.

Returns a point object where each dimension coordinate represents the testing truth value of ‘point’ dimension comprised between min and max of listed ‘points’ dimension.

In other words, we get something like:

Point(
    int(minX(points) <= point.x <= maxX(points)),
    int(minY(points) <= point.y <= maxY(points)),
    int(minZ(points) <= point.z <= maxZ(points))
)

If ‘points’ are omitted, ‘point’ is compared to current bounding box points (self.point1, self.point2).

width[source]

Bounding box’ width - read-only attribute.

class CoolWorld.geometry.WorldBoundingBox3D(*points, **options)[source]

Bases: CoolWorld.geometry.WorldBoundingBox2D

Bounding box for 3D world.

center(query=None)[source]

Build tuple of center dimensions along with query.

Parameter:
query – string of dims (default: None).

If None or omitted, ‘query’ will be replaced by “xyz” string of chars.

Any combination of dims is allowed e.g. “x”, “xy”, “xz”, “yz”, “xyz”, “yxz”, “zxy”, “zyx” and so on.

Will always return a tuple object, even for only one dimension query e.g. self.center(“x”) –> (self.center_x, ).

center_xyz[source]

Tuple center of (X, Y, Z) dimensions - read-only attribute.

Current implementation merely returns a tuple of (self.center_x, self.center_y, self.center_z).

center_z[source]

Center of Z dimension - read-only attribute.

Current implementation merely returns (self.point1.z + self.point2.z)//2.

depth[source]

Bounding box’ depth - read-only attribute.

entered(*points)[source]

Evaluate bounding box’ entered sides.

Parameter:
points – variable list of tuple coordinates or point objects.

Returns a tuple list of any current bounding box side name (‘left’, ‘right’, ‘top’, ‘bottom’, ‘front’, ‘rear’) that has been entered by given group of points.

exited(*points)[source]

Evaluate bounding box’ exited sides.

Parameter:
points – variable list of tuple coordinates or point objects.

Returns a tuple list of any current bounding box side name (‘left’, ‘right’, ‘top’, ‘bottom’, ‘front’, ‘rear’) that has been exited by given group of points.

point_type[source]

Preferred point type - read-only attribute.

Current implementation returns WorldPoint3D class type.

This can be redefined in subclasses to fit more specific needs.

size[source]

Bounding box size - read-only attribute.

Returns (width, height, depth) tuple.

class CoolWorld.geometry.WorldBoxBase2D(width=0, height=0, **options)[source]

Bases: builtins.object

Base class for boxes in a 2D world.

center_x[source]

Center of X dimension - read-only attribute.

Current implementation merely returns self.width//2.

center_xy[source]

Tuple center of (X, Y) dimensions - read-only attribute.

Current implementation merely returns a tuple of (self.center_x, self.center_y).

center_y[source]

Center of Y dimension - read-only attribute.

Current implementation merely returns self.height//2.

height[source]

Box height - read-write attribute.

normalize_dimension(value)[source]

Format value in order to fit with dimension constraints.

Parameter:
value – should be a numeric value (int or float).

Will raise ValueError if ‘value’ is not a numeric value.

Returns 0 if bool(value) is False.

size[source]

Box size - read-only attribute.

Returns (width, height) tuple.

to_dict()[source]

Dictionary representation of object attributes.

Returns dict(width=self.width, height=self.height).

to_tuple()[source]

Tuple representation of object attributes.

Returns (width, height) tuple.

width[source]

Box width - read-write attribute.

class CoolWorld.geometry.WorldBoxBase3D(width=0, height=0, depth=0, **options)[source]

Bases: CoolWorld.geometry.WorldBoxBase2D

Base class for boxes in a 3D world.

center(query=None)[source]

Build tuple of center dimensions along with query.

Parameter:
query – string of dims (default: None).

If None or omitted, ‘query’ will be replaced by “xyz” string of chars.

Any combination of dims is allowed e.g. “x”, “xy”, “xz”, “yz”, “xyz”, “yxz”, “zxy”, “zyx” and so on.

Will always return a tuple object, even for only one dimension query e.g. self.center(“x”) –> (self.center_x, ).

center_xyz[source]

Tuple center of (X, Y, Z) dimensions - read-only attribute.

Current implementation merely returns a tuple of (self.center_x, self.center_y, self.center_z).

center_z[source]

Center of Z dimension - read-only attribute.

Current implementation merely returns self.depth//2.

depth[source]

Box depth - read-write attribute.

size[source]

Box size - read-only attribute.

Returns (width, height, depth) tuple.

to_dict()[source]

Dictionary representation of object attributes.

Returns dict(width=self.width, height=self.height, depth=self.depth).

to_tuple()[source]

Tuple representation of object attributes.

Returns (width, height, depth) tuple.

class CoolWorld.geometry.WorldPoint2D(x=0, y=0)[source]

Bases: builtins.object

Geometrical point for 2D world.

cdot(other)[source]

Hadamard matrix product.

Examples:

Point(x, y).cdot(Point(a, b)) == Point(x*a, y*b)

Point(x, y, z).cdot(Point(a, b, c)) == Point(x*a, y*b, z*c)
normalize_dimension(value)[source]

Format value in order to fit with dimension constraints.

Parameter:
value – should be a numeric value (int or float).

Will raise ValueError if ‘value’ is not a numeric value.

Returns 0 if bool(value) is False.

to_dict()[source]

Dictionary representation of object attributes.

Returns dict(x=self.x, y=self.y).

to_tuple()[source]

Tuple representation of object attributes.

Returns (x, y) tuple.

x[source]

x dimension coordinate - read-write attribute.

xy[source]

(x, y) coordinates - read-only attribute.

y[source]

y dimension coordinate - read-write attribute.

class CoolWorld.geometry.WorldPoint3D(x=0, y=0, z=0)[source]

Bases: CoolWorld.geometry.WorldPoint2D

Geometrical point for 3D world.

to_dict()[source]

Dictionary representation of object attributes.

Returns dict(x=self.x, y=self.y, z=self.z).

to_tuple()[source]

Tuple representation of object attributes.

Returns (x, y, z) tuple.

xyz[source]

(x, y, z) coordinates - read-only attribute.

z[source]

z dimension coordinate - read-write attribute.

class CoolWorld.geometry.WorldVector2D(x=0, y=0)[source]

Bases: CoolWorld.geometry.WorldPoint2D

Geometrical vector for 2D world.

abs(query=None)[source]

Force vector coordinates to abs() along with query.

Parameter:
query – string of dims (default: None).

If None or omitted, ‘query’ will be replaced by “xy” string of chars.

Any combination of dims is allowed e.g. “x”, “xy”, “yx”, “y”.

Returns self.

abs_x()[source]

Force vector x coordinate to abs(x).

abs_y()[source]

Force vector y coordinate to abs(y).

flip(query=None)[source]

Flip (invert) vector coordinates along with query.

Parameter:
query – string of dims (default: None).

If None or omitted, ‘query’ will be replaced by “xy” string of chars.

Any combination of dims is allowed e.g. “x”, “xy”, “yx”, “y”.

Returns self.

flip_x()[source]

Flip vector x coordinate to -x.

flip_y()[source]

Flip vector y coordinate to -y.

neg(query=None)[source]

Negate vector coordinates along with query.

Parameter:
query – string of dims (default: None).

If None or omitted, ‘query’ will be replaced by “xy” string of chars.

Any combination of dims is allowed e.g. “x”, “xy”, “yx”, “y”.

Returns self.

neg_x()[source]

Force vector x coordinate to -abs(x).

neg_y()[source]

Force vector y coordinate to -abs(y).

class CoolWorld.geometry.WorldVector3D(x=0, y=0, z=0)[source]

Bases: CoolWorld.geometry.WorldPoint3D, CoolWorld.geometry.WorldVector2D

Geometrical vector for 3D world.

abs(query=None)[source]

Force vector coordinates to abs() along with query.

Parameter:
query – string of dims (default: None).

If None or omitted, ‘query’ will be replaced by “xyz” string of chars.

Any combination of dims is allowed e.g. “x”, “xy”, “xz”, “yz”, “xyz”, “yxz”, “zxy”, “zyx” and so on.

Returns self.

abs_z()[source]

Force vector z coordinate to abs(z).

flip(query=None)[source]

Flip (invert) vector coordinates along with query.

Parameter:
query – string of dims (default: None).

If None or omitted, ‘query’ will be replaced by “xyz” string of chars.

Any combination of dims is allowed e.g. “x”, “xy”, “xz”, “yz”, “xyz”, “yxz”, “zxy”, “zyx” and so on.

Returns self.

flip_z()[source]

Flip vector z coordinate to -z.

neg(query=None)[source]

Negate vector coordinates along with query.

Parameter:
query – string of dims (default: None).

If None or omitted, ‘query’ will be replaced by “xyz” string of chars.

Any combination of dims is allowed e.g. “x”, “xy”, “xz”, “yz”, “xyz”, “yxz”, “zxy”, “zyx” and so on.

Returns self.

neg_z()[source]

Force vector z coordinate to -abs(z).

CoolWorld.images module

Image bank management module.

Implements:

class WorldImageManager – generic image bank manager.
class CoolWorld.images.WorldImageManager(world, name=None, **options)[source]

Bases: CoolWorld.world.WorldItem

Generic image bank manager.

As a WorldItem subclass, this can be accessed through e.g. self.world.get(“worldimagemanager”) or any other arbitrary name while registering.

Feel free to subclass this in order to best meet your own specific needs.

do_step(*args, **kw)[source]

Do a game frame (step) - hook method.

Called at each step of world game’s main loop.

Current implementation does nothing.

Override this in subclasses whenever you need some action at each step of game loop.

finalize()[source]

Finalize world item - hook method.

Called after exiting world game’s main loop.

Current implementation merely clears up image bank.

Override this in subclasses whenever you need some deletion or garbage collection at the end of the game (or at the end of world item’s lifecycle).

get_image(filepath)[source]

Return an image object.

Parameter:
filepath – path to image resource file.

Returns a cached image object if already asked at least once, creates a new image object and returns it, otherwise.

Creates an image object through image_factory() hook method to let each external lib provide an image object on its own.

image_factory(filepath)[source]

Image object provider - hook method.

Parameter:
filepath – path to image resource file.

This hook method MUST be overridden in subclasses or it will raise a NotImplementedError.

Should return an image object created along with external lib specific implementation.

initialize()[source]

Initialize world item - hook method.

Called just before entering world game’s main loop.

Current implementation initializes an image bank dictionary.

Override this in subclasses whenever you need some initializations at the beginning of the game (or at the beginning of world item’s lifecycle).

CoolWorld.shapes module

Shapes module.

Implements:

class WorldShapeBase2D – mixin base class for 2D shape management.

class WorldShapeBase3D – mixin base class for 3D shape management.

class WorldShapeBox3D – shape specific class for managing 3D box objects.

class WorldShapeCircle2D – shape specific class for managing 2D circle objects.

class WorldShapeImage2D – shape specific class for managing 2D image objects.

class WorldShapePolygon2D – shape specific class for managing 2D polygon objects.

class WorldShapePolyhedron3D – shape specific class for managing 3D polyhedron objects.

class WorldShapeRectangle2D – shape specific class for managing 2D rectangle objects.

class WorldShapeSphere3D – shape specific class for managing 3D sphere objects.

class CoolWorld.shapes.WorldShapeBase2D(**options)[source]

Bases: CoolWorld.geometry.WorldAnchorage2D

Mixin base class for 2D shape management.

bbox[source]

Bounding box - read-only attribute.

This bounding box is relative to self.origin anchorage point and to self.anchor anchorage query.

bbox_type[source]

Preferred bounding box type - read-only attribute.

Current implementation returns geometry.WorldBoundingBox2D class type.

This can be redefined in subclasses to fit more specific needs.

center_point[source]

Shape’s center point - read-only attribute.

This point is relative to self.origin anchorage point and to self.anchor anchorage query.

Uses self.unit_vector for local calculations.

half_size[source]

Half dims of size - read-only attribute.

Returns half dims of size i.e. (width//2, height//2).

points_to_tuple(*points)[source]

Convert a list of given points to a tuple list of tuple coordinates.

Example: [Point(1, 2), Point(3, 4), (5, 6), [7, 8]] will be converted to ((1, 2), (3, 4), (5, 6), (7, 8)).

size[source]

Shape’s size - read-only attribute.

This attribute MUST be overridden in subclasses. Will raise a NotImplementedError otherwise.

to_tuple()[source]

Tuple representation of shape object attributes.

This attribute MUST be overridden in subclasses. Will raise a NotImplementedError otherwise.

class CoolWorld.shapes.WorldShapeBase3D(**options)[source]

Bases: CoolWorld.geometry.WorldAnchorage3D, CoolWorld.shapes.WorldShapeBase2D

Mixin base class for 3D shape management.

bbox_type[source]

Preferred bounding box type - read-only attribute.

Current implementation returns geometry.WorldBoundingBox3D class type.

This can be redefined in subclasses to fit more specific needs.

half_size[source]

Half dims of size - read-only attribute.

Returns half dims of size i.e. (width//2, height//2, depth//2).

class CoolWorld.shapes.WorldShapeBox3D(origin, width, height, depth, **options)[source]

Bases: CoolWorld.geometry.WorldBoxBase3D, CoolWorld.shapes.WorldShapeBase3D

Shape specific class for managing 3D box objects.

to_tuple()[source]

Tuple representation of shape object attributes.

class CoolWorld.shapes.WorldShapeCircle2D(origin, radius, **options)[source]

Bases: CoolWorld.shapes.WorldShapeBase2D

Shape specific class for managing 2D circle objects.

size[source]

Circle size - read-only attribute.

Returns a tuple (width, height).

to_tuple()[source]

Tuple representation of shape object attributes.

class CoolWorld.shapes.WorldShapeImage2D(origin, image, **options)[source]

Bases: CoolWorld.shapes.WorldShapeBase2D

Shape specific class for managing 2D image objects.

height[source]

Image height - read-only attribute.

size[source]

Image size - read-only attribute.

Returns a tuple (width, height).

to_tuple()[source]

Tuple representation of shape object attributes.

width[source]

Image width - read-only attribute.

class CoolWorld.shapes.WorldShapePolygon2D(origin, *coords, **options)[source]

Bases: CoolWorld.shapes.WorldShapeBase2D

Shape specific class for managing 2D polygon objects.

coords[source]

Polygon coordinates attribute (read-write).

Stores any series of point coordinates as a tuple list of tuple coordinates (simplest form).

rel_coords[source]

Relative coordinates - read-only attribute.

These coordinates are relative to ‘center_point’ attribute and to ‘unit_vector’ attribute.

rel_coords_flat[source]

Flat relative coordinates - read-only attribute.

All relative coordinates are linearized into a single tuple.

This converts a ((x1, y1), ..., (xn, yn)) tuple list of tuple coordinates to a single (x1, y1, ..., xn, yn) tuple of flat coordinates.

size[source]

Polygon size - read-only attribute.

Returns a tuple (width, height) of polygon’s bounding box.

to_tuple()[source]

Tuple representation of shape object attributes.

class CoolWorld.shapes.WorldShapePolyhedron3D(origin, *coords, **options)[source]

Bases: CoolWorld.shapes.WorldShapePolygon2D, CoolWorld.shapes.WorldShapeBase3D

Shape specific class for managing 3D polyhedron objects.

class CoolWorld.shapes.WorldShapeRectangle2D(origin, width, height, **options)[source]

Bases: CoolWorld.geometry.WorldBoxBase2D, CoolWorld.shapes.WorldShapeBase2D

Shape specific class for managing 2D rectangle objects.

to_tuple()[source]

Tuple representation of shape object attributes.

class CoolWorld.shapes.WorldShapeSphere3D(origin, radius, **options)[source]

Bases: CoolWorld.shapes.WorldShapeCircle2D, CoolWorld.shapes.WorldShapeBase3D

Shape specific class for managing 3D sphere objects.

size[source]

Sphere size - read-only attribute.

Returns a tuple (width, height, depth).

CoolWorld.shapes.run_demo()[source]

CoolWorld.sounds module

Sound management module.

Implements:

class WorldSoundManager – generic sound management class interface.
class CoolWorld.sounds.WorldSoundManager(world, name=None, **options)[source]

Bases: CoolWorld.world.WorldItem

Generic sound management class interface.

As a WorldItem subclass, this can be accessed through e.g. self.world.get(“worldsoundmanager”) or any other arbitrary name while registering.

Current implementation is simply an interface and does nothing special, as each external lib has its own approach for sound management.

Feel free to subclass this in order to best meet your own specific needs.

do_step(*args, **kw)[source]

Do a game frame (step) - hook method.

Called at each step of world game’s main loop.

Current implementation does nothing.

Override this in subclasses whenever you need some action at each step of game loop.

finalize()[source]

Finalize world item - hook method.

Called after exiting world game’s main loop.

Current implementation does nothing.

Override this in subclasses whenever you need some deletion or garbage collection at the end of the game (or at the end of world item’s lifecycle).

initialize()[source]

Initialize world item - hook method.

Called just before entering world game’s main loop.

Current implementation does nothing.

Override this in subclasses whenever you need some initializations at the beginning of the game (or at the beginning of world item’s lifecycle).

pause_sound(*args, **kw)[source]

Pause sound - hook method.

This should be implemented along with each external lib specific approach.

Call this method whenever a sound playback should be paused.

play_sound(*args, **kw)[source]

Play sound - hook method.

This should be implemented along with each external lib specific approach.

Call this method whenever a new sound should be played.

resume_sound(*args, **kw)[source]

Resume sound - hook method.

This should be implemented along with each external lib specific approach.

Call this method whenever a paused sound playback should be resumed.

stop_sound(*args, **kw)[source]

Stop sound - hook method.

This should be implemented along with each external lib specific approach.

Call this method whenever a sound playback should be stopped.

CoolWorld.tkinter_ui module

Tkinter adaptation of CoolWorld lib.

Implements:

class TkWorld2D – Tkinter adaptation of world.World2D class.

class TkWorld3D – Tkinter adaptation of world.World3D class.

class TkWorldCanvas2D – World2D adaptation of tkinter.Canvas class.

class TkWorldCanvas3D – World3D adaptation of tkinter.Canvas class.

class TkWorldEventManager – Tkinter adaptation of events.WorldEventManager class.

class TkWorldImageManager – Tkinter adaptation of images.WorldImageManager class.

class TkWorldPlayer2D – Tkinter adaptation of visual.WorldPlayer2D class.

class TkWorldPlayer3D – Tkinter adaptation of visual.WorldPlayer3D class.

class TkWorldShapeBase2D – base class for 2D shape management in a tkinter environment.

class TkWorldShapeBase3D – base class for 3D shape management in a tkinter environment.

class TkWorldShapeCircle – Tkinter adaptation of shapes.WorldShapeCircle2D class.

class TkWorldShapeImage – Tkinter adaptation of shapes.WorldShapeImage2D class.

class TkWorldShapeOval – Tkinter specific implementation for 2D oval shapes.

class TkWorldShapePolygon – Tkinter adaptation of shapes.WorldShapePolygon2D class.

class TkWorldShapeRectangle – Tkinter adaptation of shapes.WorldShapeRectangle2D class.

class TkWorldSoundManager – dummy class (Tkinter does not manage sounds at all).

class TkWorldSprite2D – Tkinter adaptation of visual.WorldSprite2D class.

class TkWorldSprite3D – Tkinter adaptation of visual.WorldSprite3D class.

class TkWorldView – Tkinter adaptation of visual.WorldView class.

class CoolWorld.tkinter_ui.TkWorld2D(tk_parent, **options)[source]

Bases: CoolWorld.world.World2D

Tkinter adaptation of world.World2D class.

end(*args, **kw)[source]

Try to break world’s game loop.

Override or extend this method in subclasses whenever you need more precise behaviour on game end request.

game_loop(fps, sequence)[source]

Game’s generic main loop.

Parameters:

fps – required number of frames per second (steps/second).

sequence – sorted sequence of world item names to manage.

Feel free to override or extend this method to best meet your own needs.

game_loop_after(delay, sequence)[source]

Actual game loop launcher (with time delay).

Parameters:

delay – required delay of time between each game step. Current implementation expects delay in milliseconds.

sequence – sequential list of world item names to manage.

This method allows deferred calls to the actual game loop for many reasons:

  • a deferred call allows to enter tkinter’s mainloop() main event management loop;
  • it avoids multiple deferred calls to a same callable;
  • it synchronizes game loop in time, according to required FPS value.
internal_loop(delay, sequence)[source]

Tkinter world’s actual game loop.

If you really need to change something, it is probably here.

class CoolWorld.tkinter_ui.TkWorld3D(tk_parent, **options)[source]

Bases: CoolWorld.world.World3D, CoolWorld.tkinter_ui.TkWorld2D

Tkinter adaptation of world.World3D class.

class CoolWorld.tkinter_ui.TkWorldCanvas2D(master=None, **options)[source]

Bases: tkinter.Canvas

World2D adaptation of tkinter.Canvas class.

DEFAULT_UNIT_VECTOR = (1, -1)
unit_vector[source]

Geometrical unit vector - read-write attribute.

Helper for local coordinates calculations.

vector_type[source]

Preferred vector type - read-only attribute.

Current implementation returns geometry.WorldVector2D class type.

This can be redefined in subclasses to fit more specific needs.

class CoolWorld.tkinter_ui.TkWorldCanvas3D(master=None, **options)[source]

Bases: CoolWorld.tkinter_ui.TkWorldCanvas2D

World3D adaptation of tkinter.Canvas class.

DEFAULT_UNIT_VECTOR = (1, -1, 1)
vector_type[source]

Preferred vector type - read-only attribute.

Current implementation returns geometry.WorldVector3D class type.

This can be redefined in subclasses to fit more specific needs.

class CoolWorld.tkinter_ui.TkWorldEventManager(world, name=None, **options)[source]

Bases: CoolWorld.events.WorldEventManager

Tkinter adaptation of events.WorldEventManager class.

Current implementation does nothing.

Please, refer to events.WorldEventManager implementation for more details.

class CoolWorld.tkinter_ui.TkWorldImageManager(world, name=None, **options)[source]

Bases: CoolWorld.images.WorldImageManager

Tkinter adaptation of images.WorldImageManager class.

Please, refer to images.WorldImageManager implementation for more details.

image_factory(filepath)[source]

Produce and return an image object.

Parameter:
filepath – path to image resource file.
class CoolWorld.tkinter_ui.TkWorldPlayer2D(world, name=None, **options)[source]

Bases: CoolWorld.tkinter_ui.TkWorldSprite2D, CoolWorld.visual.WorldPlayer2D

Tkinter adaptation of visual.WorldPlayer2D class.

Current implementation does nothing.

Please, refer to visual.WorldPlayer2D implementation for more detail.

class CoolWorld.tkinter_ui.TkWorldPlayer3D(world, name=None, **options)[source]

Bases: CoolWorld.tkinter_ui.TkWorldSprite3D, CoolWorld.visual.WorldPlayer3D

Tkinter adaptation of visual.WorldPlayer3D class.

Current implementation does nothing.

Please, refer to visual.WorldPlayer3D implementation for more detail.

class CoolWorld.tkinter_ui.TkWorldShapeBase2D(canvas)[source]

Bases: builtins.object

Base class for 2D shape management in a tkinter environment.

DEFAULT_UNIT_VECTOR = (1, -1)
finalize(*args, **kw)[source]

Finalize shape object.

Here, shape object is merely deleted from parent canvas widget.

hide(*args, **kw)[source]

Hide shape object.

initialize(**tk_options)[source]

Initialize shape object.

Parameter:
tk_options – shape’s tkinter-specific options.

Please, refer to Tkinter documentation for more detail.

lower_below(tag_or_id)[source]

Place shape object layer under given tag or id object layer.

Parameter:
tag_or_id – canvas item’s tag or id. Can also be the constant tkinter.ALL.
raise_above(tag_or_id)[source]

Place shape object layer over given tag or id object layer.

Parameter:
tag_or_id – canvas item’s tag or id. Can also be the constant tkinter.ALL.
render(new_position=None, **tk_options)[source]

Render shape object in parent canvas.

Parameters:

new_position – tuple coordinates (x, y) of anchorage origin point’s new position in parent canvas.

tk_options – shape’s tkinter-specific options.

Please, refer to Tkinter documentation for more detail.

shape_coords(*args, **kw)[source]

Shape object list of coordinates - hook method.

Should return some tkinter-compatible list of coordinates.

shape_factory(**tk_options)[source]

Shape specific builder - hook method.

Parameter:

tk_options – shape’s tkinter-specific options.

Please, refer to Tkinter documentation for more detail.

This hook method MUST be overridden in subclass or it will raise a NotImplementedError.

Creates shape on parent canvas along with its own specific options.

show(*args, **kw)[source]

Make shape object visible onto parent canvas.

class CoolWorld.tkinter_ui.TkWorldShapeBase3D(canvas)[source]

Bases: CoolWorld.tkinter_ui.TkWorldShapeBase2D

Base class for 3D shape management in a tkinter environment.

DEFAULT_UNIT_VECTOR = (1, -1, 1)
class CoolWorld.tkinter_ui.TkWorldShapeCircle(canvas, origin, radius, **options)[source]

Bases: CoolWorld.tkinter_ui.TkWorldShapeBase2D, CoolWorld.shapes.WorldShapeCircle2D

Tkinter adaptation of shapes.WorldShapeCircle2D class.

shape_factory(**tk_options)[source]

Shape specific builder - hook method.

Parameter:

tk_options – shape’s tkinter-specific options.

Please, refer to Tkinter documentation for more detail.

Creates shape on parent canvas along with its own specific options.

class CoolWorld.tkinter_ui.TkWorldShapeImage(canvas, origin, image, **options)[source]

Bases: CoolWorld.tkinter_ui.TkWorldShapeBase2D, CoolWorld.shapes.WorldShapeImage2D

Tkinter adaptation of shapes.WorldShapeImage2D class.

shape_coords(*args, **kw)[source]

Shape object list of coordinates - hook method.

Returns here self.center_point attribute.

shape_factory(**tk_options)[source]

Shape specific builder - hook method.

Parameter:

tk_options – shape’s tkinter-specific options.

Please, refer to Tkinter documentation for more detail.

Creates shape on parent canvas along with its own specific options.

class CoolWorld.tkinter_ui.TkWorldShapeOval(canvas, origin, width, height, **options)[source]

Bases: CoolWorld.tkinter_ui.TkWorldShapeBase2D, CoolWorld.shapes.WorldShapeRectangle2D

Tkinter specific implementation for 2D oval shapes.

shape_factory(**tk_options)[source]

Shape specific builder - hook method.

Parameter:

tk_options – shape’s tkinter-specific options.

Please, refer to Tkinter documentation for more detail.

Creates shape on parent canvas along with its own specific options.

class CoolWorld.tkinter_ui.TkWorldShapePolygon(canvas, origin, *coords, **options)[source]

Bases: CoolWorld.tkinter_ui.TkWorldShapeBase2D, CoolWorld.shapes.WorldShapePolygon2D

Tkinter adaptation of shapes.WorldShapePolygon2D class.

shape_coords(*args, **kw)[source]

Shape object list of coordinates - hook method.

Returns here self.rel_coords_flat attribute.

shape_factory(**tk_options)[source]

Shape specific builder - hook method.

Parameter:

tk_options – shape’s tkinter-specific options.

Please, refer to Tkinter documentation for more detail.

Creates shape on parent canvas along with its own specific options.

class CoolWorld.tkinter_ui.TkWorldShapeRectangle(canvas, origin, width, height, **options)[source]

Bases: CoolWorld.tkinter_ui.TkWorldShapeBase2D, CoolWorld.shapes.WorldShapeRectangle2D

Tkinter adaptation of shapes.WorldShapeRectangle2D class.

shape_factory(**tk_options)[source]

Shape specific builder - hook method.

Parameter:

tk_options – shape’s tkinter-specific options.

Please, refer to Tkinter documentation for more detail.

Creates shape on parent canvas along with its own specific options.

class CoolWorld.tkinter_ui.TkWorldSoundManager[source]

Bases: builtins.object

dummy class (Tkinter does not manage sounds at all).

class CoolWorld.tkinter_ui.TkWorldSprite2D(world, name=None, **options)[source]

Bases: CoolWorld.visual.WorldSprite2D

Tkinter adaptation of visual.WorldSprite2D class.

DEFAULT_UNIT_VECTOR = (1, -1)
class CoolWorld.tkinter_ui.TkWorldSprite3D(world, name=None, **options)[source]

Bases: CoolWorld.visual.WorldSprite3D

Tkinter adaptation of visual.WorldSprite3D class.

DEFAULT_UNIT_VECTOR = (1, -1, 1)
class CoolWorld.tkinter_ui.TkWorldView(canvas, world, name=None, **options)[source]

Bases: CoolWorld.visual.WorldView

Tkinter adaptation of visual.WorldView class.

CoolWorld.tkinter_ui.run_demo()[source]

CoolWorld.visual module

Visual world items module.

Implements:

class WorldPlayer2D – world item skeleton for Player sprite in 2D world.

class WorldPlayer3D – world item skeleton for Player sprite in 3D world.

class WorldSprite2D – sprite management for 2D graphical world items.

class WorldSprite3D – sprite management for 3D graphical world items.

class WorldView – world item skeleton for a View component (2D/3D worlds).

class CoolWorld.visual.WorldPlayer2D(world, name=None, **options)[source]

Bases: CoolWorld.visual.WorldSprite2D

World item skeleton for Player sprite in 2D world.

Current implementation does nothing.

Please, refer to world.WorldItemInterface for implementation details.

class CoolWorld.visual.WorldPlayer3D(world, name=None, **options)[source]

Bases: CoolWorld.visual.WorldSprite3D

World item skeleton for Player sprite in 3D world.

Current implementation does nothing.

Please, refer to world.WorldItemInterface for implementation details.

class CoolWorld.visual.WorldSprite2D(world, name=None, **options)[source]

Bases: CoolWorld.world.WorldItem

Sprite management for 2D graphical world items.

A sprite object is a visual world item in contrast to other non-visual world items such as event, image and sound managers, movement, physics and collision processors and so on.

DEFAULT_POSITION = None
DEFAULT_UNIT_VECTOR = (1, 1)
DEFAULT_VELOCITY = None
point_type[source]

Preferred point type - read-only attribute.

Current implementation returns geometry.WorldPoint2D class type.

This can be redefined in subclasses to fit more specific needs.

position[source]

Sprite’s position in world area - read-write attribute.

unit_vector[source]

Sprite’s local unit vector - read-write attribute.

Helper for local relative calculations.

vector_type[source]

Preferred vector type - read-only attribute.

Current implementation returns geometry.WorldVector2D class type.

This can be redefined in subclasses to fit more specific needs.

velocity[source]

Sprite’s velocity - read-write attribute.

class CoolWorld.visual.WorldSprite3D(world, name=None, **options)[source]

Bases: CoolWorld.visual.WorldSprite2D

Sprite management for 3D graphical world items.

A sprite object is a visual world item in contrast to other non-visual world items such as event, image and sound managers, movement, physics and collision processors and so on.

DEFAULT_UNIT_VECTOR = (1, 1, 1)
point_type[source]

Preferred point type - read-only attribute.

Current implementation returns geometry.WorldPoint3D class type.

This can be redefined in subclasses to fit more specific needs.

vector_type[source]

Preferred vector type - read-only attribute.

Current implementation returns geometry.WorldVector3D class type.

This can be redefined in subclasses to fit more specific needs.

class CoolWorld.visual.WorldView(world, name=None, **options)[source]

Bases: CoolWorld.world.WorldItem

World item skeleton for a View component (2D/3D worlds).

Current implementation does nothing.

Please, refer to world.WorldItemInterface for implementation details.

CoolWorld.visual.run_demo()[source]

CoolWorld.world module

World module.

Implements:

class Conventions – essentially naming conventions to use in lib.

class World2D – World class for 2D games.

class World3D – World class for 3D games.

class WorldItem – base class for all world components.

class WorldItemInterface – mixin interface for all WorldItem class hook methods.

class CoolWorld.world.Conventions(name=None)[source]

Bases: builtins.object

Conventions for all lib components.

Only defines a class name feature and a naming convention.

classname(instance=None)[source]

Return class name.

Parameter:
instance – object instance (default: None).

If omitted or None, ‘instance’ is replaced by ‘self’ instance.

name[source]

Read-only attribute.

Returns object’s arbitrary name.

naming_convention(name)[source]

Return name formatted along with naming convention.

Parameter:
name – object’s arbitrary name.

By default, naming convention is to lowercase(name).

class CoolWorld.world.World2D(**options)[source]

Bases: CoolWorld.world.Conventions

World class for 2D games.

The World class manages all synchronization processes between world items it may contain during its lifecycle.

DEFAULT_AREA = (640, 480)
area[source]

World’s playground area - read-write attribute.

This can be a simple tuple (width, height) or a more complex WorldArea2D(width, height) object.

This attribute always returns a geometry.WorldArea2D object instance (or whatever is defined in ‘area_type’ attribute in subclasses), no matter what has initialized it.

Example:

from CoolWorld import game
world = game.World2D()
world.area = (800, 600)
print(world.area, type(world.area)) # geometry.WorldArea2D
area_type[source]

Preferred area type - read-only attribute.

Current implementation returns geometry.WorldArea2D class type.

This can be redefined in subclasses to fit more specific needs.

end(*args, **kw)[source]

Try to break world’s game loop.

Override or extend this method in subclasses whenever you need more precise behaviour on game end request.

fps_to_delay(fps)[source]

Convert FPS value to time delay.

Parameter:
fps – numeric value expressed in frames per second (FPS) unit. Should never be less than 1.

Current implementation converts FPS value to time delay in milliseconds.

Override this method in subclasses whenever you need another time delay unit e.g. in seconds rather than milliseconds.

game_loop(fps, sequence)[source]

Game’s generic main loop.

Parameters:

fps – required number of frames per second (steps/second).

sequence – sorted sequence of world item names to manage.

Feel free to override or extend this method to best meet your own needs.

get(item_name, strict=True)[source]

Get world item by its arbitrary name.

Parameters:

item_name – world item’s arbitrary name.

strict – strict mode (default: True). Raises KeyError if strict and no registered name found, remains silent otherwise.

Use this method to get a world item object instance through its arbitrary name e.g. _player = self.world.get(“player”).

get_items(exclude=None)[source]

Return list of registered world items.

Parameter:
exclude – world item(s) to exclude (default: None). This can be just a single object instance or a list of object instances.

Please, notice returned list of world items is an unordered Python set() object.

items[source]

World items dictionary - read-only attribute.

Use this attribute with caution, as any external change may lead to unpredictable behaviour.

Unless you really know what you are doing, refer to world.items only for read-only purposes.

register(world_item, name=None)[source]

Register world item into current world.

Parameters:

world_item – world item object instance to register.

name – arbitrary name (default: None). Can be any arbitrary name, provided it is a unique one in all game’ scope.

If parameter ‘name’ is not given, the world item instance will be registered with its own ‘world_item.name’ attribute.

Registering will raise KeyError if given ‘name’ is already registered in current world.

A registered world item is internally tagged with an on-the-fly ‘world_item.registered_as_name’ attribute. This is done for easy tracking of arbitrary name registering.

run(sequence=None, fps=30)[source]

Manage world items for game’s main loop.

Parameters:

sequence – sequential list of world item names (default: None). Should be a list of all world item names to execute in a precise sequential order. If not given or None, the sequential order will be evaluated as the sorted list of all registered world item names.

fps – required number of frames per second (default: 30). A game frame is a synonym for game step.

This method first initializes all world items along with ‘sequence’ sequential order, then enters self.game_loop(fps, sequence) and after then finalizes all world items, yet along with ‘sequence’ sequential order.

sleep(delay)[source]

Suspend world activity for a time delay.

Override this hook method in subclasses whenever you need more precise behaviour to synchronize world’s pace (FPS).

unregister(item)[source]

Unregister a world item.

Parameter:
item – can be a world item arbitrary name (string) or a world item object instance.

When ‘item’ is merely an arbitrary name, silently removes world item unique occurrence of that name, if exists.

When ‘item’ is an actual world item object instance, silently removes ALL possible occurrences of that world item (multiple registering of a same instance with multiple arbitrary names).

wait()[source]

Wait until all world items are unregistered.

Will call self.wait_do_events() method in a loop while waiting for world items to leave.

wait_do_events(*args, **kw)[source]

Update events while waiting for world items to leave.

This hook method does nothing in the current implementation.

Feel free to override this in subclasses whenever you need a more precise behaviour to update events while waiting for world items to all leave the current world.

class CoolWorld.world.World3D(**options)[source]

Bases: CoolWorld.world.World2D

World class for 3D games.

The World class manages all synchronization processes between world items it contains.

DEFAULT_AREA = (1000, 1000, 1000)
area_type[source]

Preferred area type - read-only attribute.

Current implementation returns geometry.WorldArea3D class type.

This can be redefined in subclasses to fit more specific needs.

class CoolWorld.world.WorldItem(world, name=None, **options)[source]

Bases: CoolWorld.world.Conventions, CoolWorld.world.WorldItemInterface

Base class for all World components.

This is THE class to be subclassed each time you need a specific world item e.g. Sprite, Player, Enemy, View, ImageManager, SoundManager, MovementManager, CollisionManager and so on.

do_threaded_step(*args, **kw)[source]

Execute only one step of game loop in a separate thread of control.

Will raise RuntimeError if previous step takes too long to execute, which somehow implies world item’s step is globally too slow to fit with game’s current pace.

enter_world(world=None)[source]

Enter a new world.

Parameter:
world – new parent world (default: None). If None or omitted, will be replaced by ‘self.world’ member attribute.

Will raise KeyError on registering if world item has already been registered to the given world and never been unregistered before.

leave_world(world=None)[source]

Leave world.

Parameter:
world – new parent world (default: None). If None or omitted, will be replaced by ‘self.world’ member attribute.

Will silently unregister world item from given world.

move_to_world(world)[source]

Move to a new world.

Parameter:
world – new parent world to enter after having left current world behind.

This method simply leaves current world and enters new given world.

class CoolWorld.world.WorldItemInterface[source]

Bases: builtins.object

Mixin interface.

Gathers all hook methods to be reimplemented in subclasses.

do_step(*args, **kw)[source]

Do a game frame (step) - hook method.

Called at each step of world game’s main loop.

Current implementation does nothing.

Override this in subclasses whenever you need some action at each step of game loop.

finalize()[source]

Finalize world item - hook method.

Called after exiting world game’s main loop.

Current implementation does nothing.

Override this in subclasses whenever you need some deletion or garbage collection at the end of the game (or at the end of world item’s lifecycle).

initialize()[source]

Initialize world item - hook method.

Called just before entering world game’s main loop.

Current implementation does nothing.

Override this in subclasses whenever you need some initializations at the beginning of the game (or at the beginning of world item’s lifecycle).

CoolWorld.world.run_demo()[source]

Module contents

Package initialization module.

Current implementation allows to get all class defs (except those of tkinter_ui module) by simply importing package name.

Example:

import CoolWorld
world = CoolWorld.World2D()
player = CoolWorld.WorldPlayer2D(world, name="player")
enemy = CoolWorld.WorldSprite2D(world, name="enemy")
view = CoolWorld.WorldView(world, name="view")
world.run()

Notice: it is fancier to use:

from CoolWorld import game
world = game.World2D()
player = game.WorldPlayer2D(world, name="player")
enemy = game.WorldSprite2D(world, name="enemy")
view = game.WorldView(world, name="view")
world.run()