graphics—Graphic subclasses

class Colour(colour, rect, layer=0)

Bases: engine.gfx.graphic.Graphic

A solid rect of colour.

Parameters:

• colour – a colour to draw, as accepted by engine.util.normalise_colour().
• rect – Pygame-style rect to draw in, or just a (width, height) size to use a rect with position (0, 0).
• layer – as taken by Graphic.

fill() corresponds to a builtin transform.

colour

As taken by constructor; set as necessary.

fill(colour)

Fill with the given colour (like colour).

class Text(text, renderer, pos=(0, 0), options={}, layer=0)

Bases: engine.gfx.graphic.Graphic

Graphic displaying rendered text.

Parameters:

• text – text to render; may contain line breaks to display separate lines.
• renderer – text.TextRenderer instance or the name a renderer is stored under in Game.text_renderers.
• pos – as taken by Graphic.
• options – rendering options to override defaults, as taken by TextRenderer.render(). All options can be get and set as properties of this instance, and all are guaranteed to exist, even if not given in this argument.
• layer – as taken by Graphic.

nlines = None

Number of lines of text rendered.

text

Text to render (as taken by constructor).

renderer

text.TextRenderer instance to use.

class Animation(imgs, pos=(0, 0), layer=0, [scheduler, ]pool=conf.DEFAULT_RESOURCE_POOL, res_mgr=conf.GAME.resources)

Bases: engine.gfx.graphic.Graphic

An animated graphic.

Parameters:

• imgs – a sequence of images as part of the animation; each can be a Pygame surface, a filename to load an surface from, or a Graphic instance (in which case it is removed from any GraphicsManager it is in). Note that a util.Spritemap instance is a valid form for this argument.
• scheduler – sched.Scheduler instance to use for timing; if not given, animations can only be played when the graphic is contained by a GraphicsManager (and trying to do so otherwise raises RuntimeError).

Other arguments are as taken by Graphic.

Note that when an animation is playing and the image changes, Graphic.anchor is respected.

For example, to play the frames in a spritemap consisting of a single row:

Animation(Spritemap('map.png', 4)).add('run', frame_time=.1).play('run')

graphics = None

list of imgs as passed to the constructor, except that they are never filenames.

sequences = None

{name: (indices, frame_time)} frame sequences (‘animations’) as added through add().

scheduler = None

The scheduler argument passed to the constructor.

playing = None

The currently playing sequence (name), or None.

queued = None

list of queued sequences to play after the current sequence has finished, each (name, repeat, frame_time, cb) as added through queue(), starting with the first to be played. Items may be removed manually.

repeat = None

The current repeat of the playing sequence, starting from 0 if it hasn’t started repeating yet, or None.

repeats = None

The total number of repeats that will be performed for the currently playing sequence (not including the first playthrough), or True if it will play forever, or None.

frame = None

The current frame in the currently playing sequence (within the current repeat), as an integer starting from 0, or None.

graphic

The currently visible graphic, as an index in graphics.

frame_time

A default for the time between animation frames.

This is a value in seconds, that applies for all animation sequences. If not set, a value must be defined for each sequence. Changes do not take effect until the current frame has finished, if any is running.

speed

Running speed of any animation.

This is a multiplier, where 1 is the default speed, and anything higher decreases frame times. Changes do not take effect until the current frame has finished, if any.

add(name, *indices[, frame_time]) → self

Add a sequence to sequences to play back later.

Parameters:

• name – the name to give the sequence (any hashable object). If a sequence with this name already exists, it is overwritten; if it is currently playing or queued, it is stopped/unqueued.
• indices – any number of indices in graphics, defining the sequence of frames, or pass none for all frames in order.
• frame_time – a default for the time between animation frames in seconds whenever this sequence is played. If not given, a value must be defined either through the constructor or each time the sequence is played.

add_multi(sequences) → self

Add a number of frame sequences.

Parameters:sequences – {name: data}, where data can be an indices list or (indices[, frame_time]), and each of these is as taken by add().

rm(*names) → self

Remove sequences with the given names.

Missing items are ignored.

play(name, repeat=True[, frame_time][, cb]) → self

Play a frame sequence.

Parameters:

• name – sequence name to play.
• repeat – whether to repeat the sequence once it has finished. True to repeat forever, else a number of repeats to perform (that is, the sequence is played (repeats + 1) times). (False is also valid.)
• frame_time – the time between animation frames in seconds. If not given, a value must be defined either as through the constructor or in add().
• cb – a function to call when the animation ends (but not if it is stopped through stop() or by starting another animation).

If a sequence is already being played, that sequence is canceled.

pause() → self

Pause the currently running sequence, if any.

unpause() → self

Unpause the currently running sequence, if paused.

stop(n_queued) → self

Stop the currently running sequence, if any.

Parameters:n_queued – the number of subsequent queued sequences to cancel after stopping the running sequence.

queue(name, repeat=True[, frame_time][, cb]) → self

Queue a frame sequence for playing after any running sequence.

Arguments are as taken by play().

queue_multi(*sequences) → self

Queue multiple frame sequences.

Parameters:sequences – any number of (name, repeat=True[, frame_time][, cb]) tuples, where arguments are as taken by play().

unqueue(*names) → self

Remove frame sequences from the queue by name.

Parameters:names – any number of sequence names; missing items are ignored.

class Tilemap(grid, tile_data, [tile_types, ]pos=(0, 0), layer=0, [translate_type, ]cache_graphic=False, pool=conf.DEFAULT_RESOURCE_POOL, res_mgr=conf.GAME.resources)

Bases: engine.gfx.graphic.Graphic

A finite, flat grid of tiles.

Parameters:

• grid – a util.grid.Grid defining the size and shape of the tiles in the tilemap, or the tile_size argument to util.grid.Grid to create a new one with standard parameters.
• tile_data –

  a way of determining the tile type ID for each (x, y) tile in the grid, which is any object. This can be:

  • a list of columns, where each column is a list of IDs;
  • a string with rows delimited by line breaks and each row a whitespace-delimited set of string IDs;
  • (s, col_delim, row_delim) to specify custom delimiter characters for a string s, where either or both delimiters can be None to split by whitespace/line breaks;
  • a filename from which to load a string with delimited IDs (the name may not contain whitespace);
  • (filename, col_delim, row_delim) for a custom-delimited string in a file;
  • a Graphic, Pygame surface or filename (may not contain whitespace) to load an image from, and use the (r, g, b[, a]) colour tuples of the pixels in the surface as IDs;
  • if grid is a util.grid.Grid: a function that takes col and row arguments as column and row indices in the grid, and returns the corresponding tile type ID; or
  • if grid is not a util.grid.Grid: (get_tile_type, w, h), where get_tile_type is a function as defined previously, and w and h are the width and height of the grid, in tiles.

• tile_types –

  a tile_type_id -> tile_graphic mapping—either a function or an object that supports indexing. If not given, the identity function is used. tile_type_id is the tile type ID obtained from the tile_data argument. tile_graphic determines how the tile should be drawn; it may be:

  • None for an an empty (transparent) tile;
  • a colour (as taken by engine.util.normalise_colour()) to fill with;
  • a Graphic, Pygame surface or filename to load from, to copy aligned to the centre of the tile, clipped to fit; or
  • (graphic, alignment=0, rect=graphic_rect) with alignment or rect in any order or omitted, and graphic as in the above form. alignment is as taken by engine.util.align_rect(), and rect is the Pygame-style rect within the source surface of graphic to copy from. Regardless of alignment, rect is clipped to fit in the tile around its centre.

  Note that a util.Spritemap is a valid form for this argument.

• pos,layer – as taken by Graphic.
• translate_type – a function that takes tile type IDs obtained from the tile_data argument and returns the ID to use with the tile_types argument in obtaining tile_graphic; does nothing by default.
• cache_graphic – whether to cache and reuse tile_graphic for each tile type. You might want to pass True if requesting tile_graphic from tile_types generates a surface. If True, tile type IDs must be hashable (after translation by translate_type).
• pool,res_mgr – as taken by Graphic.

This is meant to be used for static tilemaps—that is, where the appearance of each tile type never changes.

grid = None

The util.grid.Grid covered.

update_from(tile_data, from_disk=False)

Update tiles from a new set of data.

Parameters:

• tile_data – as taken by the constructor.
• from_disk – whether to force reloading from disk, if passing an image filename.

class Grid(grid, gap_colour='aaa', bg_colour='0000', pos=(0, 0), layer=0)

Bases: engine.gfx.graphic.Graphic

Drawable wrapper for util.grid.Grid.

Parameters:

• grid – a util.grid.Grid instance.
• gap_colour – colour in-between tiles, as accepted by engine.util.normalise_colour(); may have alpha.
• bg_colour – colour within tiles, as accepted by engine.util.normalise_colour().
• pos,layer – as taken by Graphic.

class InfiniteGrid(grid, rect, gap_colour='aaa', bg_colour='0000', pos=(0, 0), layer=0)

Bases: engine.gfx.graphic.Graphic

Drawable wrapper for util.grid.InfiniteGrid.

Parameters:

• grid – a util.grid.InfiniteGrid instance.
• rect – Pygame-style rect within grid to draw.
• gap_colour – colour in-between tiles, as accepted by engine.util.normalise_colour(); may have alpha.
• bg_colour – colour within tiles, as accepted by engine.util.normalise_colour().
• pos,layer – as taken by Graphic.

grid = None

As passed to the constructor.

view_rect

As the rect argument taken by the constructor.

Graphic.anchor is respected when this is changed.

gap_colour

As passed to the constructor.

bg_colour

As passed to the constructor.