pygamepal package

pygamepal.animator

class pygamepal.animator.Animator

Bases: object

Changes any object attribute’s numerical value over time.

Example Animator code.

addAnimation(object, attribute, newValue, duration, easingFunction=<function easeLinear>, type=<class 'float'>)

Add a new Animation to the Animator.

Parameters:

• object (Object) – The object to animate a value for.

• attribute (str) – A string representation of the attribute to animate.

• newValue (float) – The new end value to animate to.

• duration (float) – The time to animate from the old to new value.

• easingFunction (func(x)) – The easing function for the animnation (default = pygamepal.easeLinear).

• type (type) – Parameter type (avoids type errors (e.g. if set to int), default = float).

update(deltaTime=1)

Updating the Animator updates each Animation in the Animator. Must be called once per frame.

pygamepal.button

class pygamepal.button.Button(input, position=(0, 0), size=(100, 50), text=None, foregroundColor='white', backgroundColor='black', borderWidth=1, borderColor='white', image=None, onHighlighted=None, onSelected=None, updateMethod=None, drawMethod=None, keyCode=None)

Bases: object

Used to provide input, and can be controlled by mouse and/or keypress.

Example Button code.

Parameters:

• input (pygamepal.Input) – The input object used to control the button.

• position ((int, int)) – The (x, y) position of the button on the drawn surface (default = (0, 0)).

• text (str) – Text to display on the button (default = None).

• foregroundColor (pygame.Color) – Foreground color, used to draw the button text and border (default = ‘white).

• backgroundColor (pygame.Color) – Background color, used to draw the button background (default = ‘black).

• borderWidth (int) – Width of the button border (default = 1).

• borderColor (pygame.Color) – Color of the button border (default = ‘white’).

• image (pygame.Texture) – Button background image (default = None).

• onHighlighted (function(pygamepal.Button)) – A function called when the mouse position intersects with the button position (default = None).

• onSelected (function(pygamepal.Button)) – A function called when the button is clicked, or the relevant button pressed (default = None).

• updateMethod (function(pygamepal.Button)) – Used to override the default update method of a button (default = None).

• drawMethod (function(pygamepal.Button, pygame.Surface)) – Used to override the default draw method of a button (default = None).

• keyCode (pygame.Key) – The keypress associated with selecting the button (default = None).

draw(surface)

Must be called once per frame if the button is not being used as part of a pygamepal.Scene.

Parameters:

surface (pygame.Surface) – The surface to draw to.

drawBackground(surface)

Draws the button background. Can be called from a custom button.drawMethod function.

Parameters:

surface (pygame.Surface) – The surface to draw to.

drawBorder(surface)

Draws the button border. Can be called from a custom button.drawMethod function.

Parameters:

surface (pygame.Surface) – The surface to draw to.

drawImage(surface)

Draws the button image. Can be called from a custom button.drawMethod function.

Parameters:

surface (pygame.Surface) – The surface to draw to.

drawText(surface)

Draws the button text. Can be called from a custom button.drawMethod function.

Parameters:

surface (pygame.Surface) – The surface to draw to.

property isHighlighted

Returns True is the mouse position intersents with the button.

property isSelected

Returns True is the button keyCode is pressed, or if the button is clicked.

setHighlighted()

Should be called within a custom button.updateMethod in order to update the button ‘highlighted’ status. A button is highlighted if the mouse is within the button bounds.

setSelected()

Should be called within a custom button.updateMethod in order to update the button ‘selected’ status. A button is selected if either the keyCode is pressed, or if the mouse button is pressed within the button bounds.

update()

Must be called once per frame if the button is not used as part of a pygamepal.Scene.

pygamepal.camera

class pygamepal.camera.Camera(position=(0, 0), size=(640, 480), target=(0, 0), lazyFollow=0, zoom=1, minZoom=0.1, maxZoom=10, lazyZoom=0, backgroundColor='cornflowerblue', borderColor='black', borderThickness=2, clamp=False, clampRect=(0, 0, 1000, 1000), oscillateSpeed=0.2, shakeMagnitude=30, shakeDirection=(1, 0), shakeDampening=0.4, shakeNoise=0.8)

Bases: object

A camera can be used to render any source surface to another destination surface, using its attributes (size, position, target position, zoom, etc.).

Example Camera code.

Parameters:

• position ((int, int)) – the top-left (x, y) coordinate for the camera.

• size ((int, int)) – the size (w, h) of the camera (default = (640, 480), or the parent Scene size if used within a Scene).

• target ((int, int)) – the coordinate (x, y) of the source surface to draw at the center of the camera (default = (0, 0)).

• lazyFollow (float) – the delay when updating the camera target. 0 = instant snap to target, 1 = no movement (default = 0).

• zoom (float) – the amount to scale the source target (default = 1).

• minZoom (float) – the minimum allowed zoom (default = 0.1).

• maxZoom (float) – the maximum allowed zoom (default = 10).

• lazyZoom (float) – the delay when updating the zoom calue. 0 = instant zoom, 1 = no change in zoom (default = 0).

• backgroundColor (pygame.Color) – the background color (default = ‘cornflowerblue’).

• borderColor (pygame.Color) – the color of the border (default = ‘black’).

• borderThickness (int) – the thickness of the border(default = 2).

• clamp (bool) – specifies whether the camera should stay within a specific boundary of the source surface (default = False).

• clampRect ((int, int, int, int)) – the boundary (x, y, w, h) of the source surface that the camera should stay within.

• oscillateSpeed (float) – the speed at which the camera should shake (default = 0.2).

• shakeMagnitude (int) – the magnitude of the camera shake (default = 30).

• shakeDirection ((float, float)) – the (x, y) direction of the shake (default = (1, 0)).

• shakeDampening (float) – the reduction in camera shake magnitude each frame (default = 0.4).

• shakeNoise (float) – the amount of random noise to add to the shake (default = 0.8).

draw(surface, destSurface)

Draws the source surface to the destination surface, using the camera attributes. This method must be called each frame if using a camera in isolation, but the method is called automatically for cameras with a parent scene.

Parameters:

• surface (pygame.Surface) – the surface to draw.

• destSurface (pygame.Surface) – the surface to draw to.

property lazyFollow

Get / set the lazy follow value, between 0 and 1.

property lazyZoom

Get / set the lazy zoom value, between 0 and 1.

setTarget(value, instant=False)

Set the camera target position. This method permits the instant setting of a position.

Parameters:

instant (bool) – set the position instantly, ignoring the stored ‘lazyFollow’ value (default = False).

setZoom(value, instant=False)

Set the camera target zoom value. This method permits the instant setting of the zoom.

Parameters:

instant (bool) – set the zoom value instantly, ignoring the stored ‘lazyZoom’ value (default = False).

shake(direction=None)

Start a camera shake.

Parameters:

direction (tuple(float, float)) – the (x, y) direction of the shake (default = None, use the stored direction).

update(deltaTime=1)

Updates the camera target position and, zoom and shake. This method must be called each frame if using a camera in isolation, but the method is called automatically for cameras with a parent scene.

Parameters:

deltaTime (float) – the game time elapsed since the last frame (default = 1).

property zoom

Get / set the zoom value (between specified ‘minZoom’ and ‘maxZoom’ values).

pygamepal.collider

class pygamepal.collider.Collider(position=(0, 0), size=(0, 0), offset=(0, 0), drawColor='red')

Bases: object

A collider is an area for which other colliders should not enter. A collider can be used independently, or as part of a sprite.

Example Collider code.

Example Sprite Collider code.

Param:

draw(surface)

Draw method doesn’t need to be called, unless the collider is being used independently and needs to be seen. (Note: to see colliders used as part of a pygamepal.Scene or pygamepal.Sprite, set pygamepal.DEGUG = True.)

property h

Get / set the height.

update()

Update method needs to be called for a collider if used independently (i.e. if not as part of a pygamepal.Scene or pygamepal.Sprite).

property w

Get / set the width.

property x

Get / set the x position.

property y

Get / set the y position.

pygamepal.dialogue

class pygamepal.dialogue.Dialogue(position=(0, 0), size=(200, 100), font=None, backgroundColor=None, textColor='black', borderColor='black', borderWidth=0, padding=10, textEffect='none', tickSpeed=4, advanceTextSymbol='>', tickSound=None, borderRadius=0, visible=True, custonDrawMethod=None)

Bases: object

Displays one or more pages of dialogue.

Example Dialogue code.

Parameters:

• position ((int, int)) – The (x, y) top-left position of the box (default = (0, 0)).

• size ((int, int)) – The (width, height) size of the box (default = (50, 50)).

• font (pygame.Font) – The text font (default = None, which uses pygamepal.sysFont).

• backgroundColor (pygame.Color) – Dialogue box background color (default = None).

• textColor (pygame.Color) – Text color (default = ‘black’).

• borderColor (pygame.Color) – Box and texture border color (default = ‘black’).

• borderWidth (int) – The width of the border, in pixels (default = 0).

• paddingWidth (int) – The space in pixels between elements (default = 10).

• textEffect (str) – Either ‘none’ or ‘tick’ (default = ‘none’).

• tickSpeed (int) – The delay between showing each character (if textEffect == ‘tick’ only, default = 4).

• advanceTextSymbol (str) – The string to show at the end of pages 0 to n-1 of dialogue (default = ‘>’).

• tickSound (pygame.Sound) – Sound to play when advancing the text (if textEffect == ‘tick’ only, default = None).

• borderRadius (int) – Bevel on the edges of the borders (default = 0).

• visible (bool) – Vibisility of the dialogue box (default = True).

• customDrawMethod (function) – Provide an alternative draw() method (default = None).

addPage(text, texture=None, textureAlignment='left', textureBackgroundColor=None)

Adds a page of dialogue to the dialogue box.

Parameters:

• text (str) – The text to display.

• texture (pygame.texture) – The texture to display with the text (default = None).

• textureAlignment (str) – Position of the texture (‘left’ or ‘right’, default = ‘left’).

• textureBackgroundColor (pygame.Color) – The texture background color (default = None).

advance()

Advances the dialogue. This means firstly showing all text for the current page, and then moving to the next page of dialogue.

draw(surface)

Draws the dialogue box, along with the current page of text.

Parameters:

deltaTime (float) – the game time elapsed since the last frame (default = 1).

getText(split=True)

Get the current page of text. If the text has a ‘tick’ effect, only the currently visible text is returned.

Parameters:

split (bool) – Returns a list of text, split according to the available

text width (default = True).

update(deltaTime=1)

Updates the dialogue box, once per frame.

Parameters:

deltaTime (float) – the game time elapsed since the last frame (default = 1).

pygamepal.dialoguePage

class pygamepal.dialoguePage.DialoguePage(parent, text, texture=None, textureAlignment='left', textureBackgroundColor=None)

Bases: object

Pages for the Dialogue class (Users of the PygamePal library should not need to use this class directly. Instead, it is used by pygamepal.Dialogue).

Parameters:

• parent (pygamepal.Dialogue) – The Dialogue object in which the DialoguePage exists.

• text (str) – The page of text.

• texture (pygame.Texture) – The texture to display with the text (default = None).

• alignment (string) – The alignment of the texture (either ‘left’ or ‘right’, default = ‘left’).

• textureBackgroundColor (pygamepal.Color) – The color to disply behind the texture (default = None).

calculateTextOffset()

calculateTextWidth()

Calculates the available width for the text.

calculateTexturePosition()

Calculates the (x, y) position of the texture.

calculateTextureSize()

Calculates the (w, h) size of the texture, based on the available space.

property text

Get / set the page text.

pygamepal.drawText

pygamepal.drawText.drawText(surface, text, position=[0, 0], font=None, antialias=True, color='white', backgroundColor=None, centerX=False, centerY=False)

Draw text.

Parameters:

• surface (pygame.Surface) – The surface to draw to.

• text (str) – The text to draw.

• position ((int, int)) – The (x, y) position to draw on the specified surface (default = (0, 0)).

• font (pygame.Font) – The font to draw the text in (default = pygamepal.sysFont).

• antialias (bool) – Antialias text (default = True).

• color (pygame.Color) – Text color (default = ‘white’).

• backgroundColor (pygame.Color) – Background text color (default = None).

• centerX (bool) – Center horizontally (default = False).

• centerY (bool) – Center vertically (default = False).

pygamepal.drawText.splitText(text=None, width=None, font=None)

pygamepal.flatten

pygamepal.flatten.flatten(list)

Flatten a multi-dimensional list into a single list.

Parameters:

list (list(list(any))) – the multi-dimensional list to flatten.

Return list(any) newList:

the flattened, single list.

pygamepal.game

class pygamepal.game.Game(size=(640, 480), caption='', fps=60, fullscreen=False)

Bases: object

Create a game without setup or boilerplate code. A Game allows you to add scenes, triggers, colliders, buttons and sprites.

Example Game code.

Parameters:

• size ((int, int)) – The size of the game window (default = (640, 480)).

• caption (str) – The game window caption (default = ‘’).

• fps (int) – The frames-per-second of the game (default = 60).

• fullscreen (bool) – Fullscreen flag.

addButton(button)

Adds a pygamepal.Button to the game.

Parameters:

button (pygamepal.Button) – The button to add to the game.

addCollider(collider)

Add a pygamepal.Collider to the game.

Parameters:

collider (pygamepal.Collider) – The collider to add to the game.

addSprite(sprite)

Adds a pygamepal.Sprite to the game.

Parameters:

sprite (pygamepal.Sprite) – The sprite to add to the game.

addTrigger(trigger)

Adds a pygamepal.Trigger to the game.

param pygamepal.Trigger trigger: The trigger to remove from the game.

draw()

Optional, user-defined method. Called once per frame of the game, after update() is called.

property icon

Get / set the game icon.

init()

Optional, user-defined method. Init() is called once when a game is created.

quit()

Call to end the game.

removeButton(button)

Removes a pygamepal.Button from the game.

Parameters:

button (pygamepal.Button) – The button to remove from the game.

removeCollider(collider)

Removes a pygamepal.Collider from the game.

Parameters:

collider (pygamepal.Collider) – The collider to remove from the game.

removeSprite(sprite)

Removes a pygamepal.Sprite from the game.

Parameters:

sprite (pygamepal.Sprite) – The sprite to remove from the game.

removeTrigger(trigger)

Removes a pygamepal.Trigger from the game.

Parameters:

trigger (pygamepal.Trigger) – The trigger to remove from the game.

run()

Call to start the game.

update(deltaTime=1)

Optional, user-defined method. Called once per frame of the game.

Parameters:

deltaTime (float) – Time elapsed since last update call.

pygamepal.input

class pygamepal.input.Input(longPressDuration=60, doublePressTimeout=30)

Bases: object

Handle Pygame input more easily, including key/mouse press, release, long-press and double-press.

Example Key Input code.

Example Mouse Input code.

Parameters:

• longPressDuration (int) – The number of milliseconds/frames a key needs to be held to register a long press (default = 60).

• mouseDoublePressTimeout (int) – The maximum number of frames between mouse button presses to register a double-press (default = 30).

getKeyDownDuration(keyCode)

Returns the number of frames a keyCode has been held down.

Parameters:

keyCode (pygame.Key) – The key to check.

getKeyLongPressPercentage(keyCode)

Returns keyCode progress towards a long press (0%-100%).

Parameters:

keyCode (pygame.Key) – The key to check.

getMouseButtonDownDuration(mouseButton)

Returns the number of frames a mouse button has been held down.

Parameters:

mouseButton (int) – The mouse button to check.

getMouseButtonLongPressPercentage(mouseButton)

Returns mouse button progress towards a long press (0%-100%).

Parameters:

mouseButton (int) – The mouse button to check.

getMouseCursorPosition()

Returns the pygame mouse pointer position.

getMouseDirection()

Returns the (x,y) movement of the mouse. e.g: - (-1, -1) = North-West movement. - (1, 1) = South-East movement.

isKeyDoublePressed(keyCode)

Returns true if the key denoted by keyCode has been double-pressed during the current frame.

Parameters:

keyCode (pygame.Key) – The key to check.

isKeyDown(keyCode)

Returns true if the key denoted by keyCode is held down during the current frame.

Parameters:

keyCode (pygame.Key) – The key to check.

isKeyLongDown(keyCode)

Returns true if the key denoted by keyCode is held down for a long press during the current frame.

Parameters:

keyCode (pygame.Key) – The key to check.

isKeyLongPressed(keyCode)

Returns true if the key denoted by keyCode has achieved a long press in the current frame.

Parameters:

keyCode (pygame.Key) – The key to check.

isKeyPressed(keyCode)

Returns true if the key denoted by keyCode has been pressed down during the current frame.

Parameters:

keyCode (pygame.Key) – The key to check.

isKeyReleased(keyCode)

Returns true if the key denoted by keyCode has been released during the current frame.

Parameters:

keyCode (pygame.Key) – The key to check.

isMouseButtonDoublePressed(mouseButton)

Returns true if the mouse button specified has been double-pressed in the current frame.

Parameters:

mouseButton (int) – The mouse button to check.

isMouseButtonDown(mouseButton)

Returns true if the mouse button specified is held down during the current frame.

Parameters:

mouseButton (int) – The mouse button to check.

isMouseButtonLongDown(mouseButton)

Returns true if the mouse button specified is held down for a long press during the current frame.

Parameters:

mouseButton (int) – The mouse button to check.

isMouseButtonLongPressed(mouseButton)

Returns true if the mouse button specified has achieved a long press in the current frame.

Parameters:

mouseButton (int) – The mouse button to check.

isMouseButtonPressed(mouseButton)

Returns true if the mouse button specified has been pressed in the current frame.

Parameters:

mouseButton (int) – The mouse button to check.

isMouseButtonReleased(mouseButton)

Returns true if the mouse button specified has been released in the current frame.

Parameters:

mouseButton (int) – The mouse button to check.

update(deltaTime=1)

Call once per frame to update. (Note: only needs to be called if using independently (i.e. not as part of a game).)

Parameters:

deltaTime (float) – Time elapsed since last frame (default = 1).

pygamepal.lighting

class pygamepal.lighting.Light(position=(0, 0), radius=100, name=None, on=True)

Bases: object

A light to add to the pygamepal.Lighting system.

Example Lighting code.

Parameters:

• position ((int, int)) – Light position on the drawn surface.

• radius (int) – The radius of the light.

• name (str) – Light name (for getting and controlling if required, default = None).

• on (bool) – Light visibility (default = True).

property radius

Get / set the radius value (is set to 0 if given negative value).

toggle()

Toggle the light visibility.

class pygamepal.lighting.Lighting(surfaceSize, lightLevel=0)

Bases: object

addLight(light)

Adds a light to the lighting system.

Parameters:

pygamepal.Light – The light to add.

draw(surface)

Draws all light in the lighting system.

Parameters:

surface (pygame.Surface) – The surface to draw to.

getLight(name)

Get light by name. Returns None if no light exists.

Parameters:

name (str) – The name of the light to get.

property lightLevel

Get / Set the ambient light level (between 0 (dark) and 1 (light), default = 0).

update(deltaTime=1)

Updates the lighting system, including all lights.

Parameters:

deltaTime (float) – The elapsed time cince the last update (default = 1).

pygamepal.particleEmitter

class pygamepal.particleEmitter.ParticleEmitter(emitterPosition=(0, 0), emitterSize=(0, 0), emitterLifetime=100, emitterVelocity=(0, 0), emitterAcceleration=(0, 0), emitterParticleDelay=5, particleVelocityMin=(-1, -1), particleVelocityMax=(1, 1), particleAccelerationMin=(0, 0), particleAccelerationMax=(0, 0), particleLifetime=100, particleSize=20, particleSizeDecay=0.2, particleColors=['white'])

Bases: object

A marticle emitter creates particles for the duration of its lifetime, with the properties specified.

Example Particles code.

Particle emitter attributes:

Parameters:

• emitterPosition ((int, int)) – The (x, y) top-left position of the emitter (default = (0, 0)).

• emitterSize ((int, int)) – The (w, h) size of the emitter. Particles are created randomly within the emitter bounds (default = (0, 0)).

• emitterLifetime (int) – The emitter only emits particles during its lifetime (-1 = forever, default = 100).

• emitterVelocity ((float, float)) – The (x, y) velocity of the emitter (default = no velocity (0, 0)).

• emitterAcceleration ((float, float)) – The (x, y) acceleration of the emitter (default = no acceleration (0, 0)).

• emitterParticleDelay (float) – The delay between particles emitted (default = 5).

Particle attributes:

Parameters:

• particleVelocityMin ((float, float)) – The minimum (x, y) velocity of a particle (default = (-1, -1)). Emitted particles are given a random velocity between the minimum and maximum.

• particleVelocityMax ((float, float)) – The maximum (x, y) velocity of a particle (default = (1, 1)). Emitted particles are given a random velocity between the minimum and maximum.

• particleAccelerationMin ((float, float)) – The minimum (x, y) acceleration of a particle (default = (0, 0)). Emitted particles are given a random acceleration between the minimum and maximum.

• particleAccelerationMax ((float, float)) – The maximum (x, y) acceleration of a particle (default = (0, 0)). Emitted particles are given a random acceleration between the minimum and maximum.

• particleLifetime (int) – Each particle is destroyed at the end of its lifetime (default = 100).

• particleSize (int) – The radius of each particle (default = 20).

• particleSizeDecay (float) – The amount to decrement the particle size each frame / per second (default = 0.2).

• particleColors (list(pygame.Color)) – Emitted particles are randomly given a color from the list (default = [‘white’]).

draw(surface)

Must be called once per frame to draw the emitter’s particles.

Parameters:

surface (pygame.Surface) – The surface to draw to.

update(deltaTime=1)

Must be called once per frame to update the particle emitter and its particles.

Parameters:

deltaTime (float) – The time elapsed since the last update (default = 1).

pygamepal.particles

class pygamepal.particle.Particle(position, velocity, acceleration, lifetime, size, sizeDecay, color)

Bases: object

A single particle created by a particle emitter. (There is no need to use this class directly, as particle emitters create particles themselves.)

Parameters:

• position ((int, int)) – The top-left (x, y) position of the particle.

• velocity ((float, float)) – The (x, y) velocity vector, with (0, 0) being stationary.

• acceleration ((float, float)) – The (x, y) acceleration vector, with (0, 0) = no acceleration.

• lifetime (int) – The time after which the particle is deleted.

• size (int) – The radius of the particle.

• sizeDecay (float) – The amount to decrement the size each frame.

• color (pygame.Color) – The particle color.

draw(surface)

Draw method called by the owner particle emitter.

Parameters:

surface (pygame.Surface) – The surface to draw to.

update(deltaTime=1)

Update method called once per frame by the owner particle emitter.

Parameters:

deltaTime (float) – The time since the last update (default = 1).

pygamepal.scene

class pygamepal.scene.Scene(game, surfaceSize=None)

Bases: object

A pygamepal.Game is made up of one or more scenes, which includes a camera, sprites, triggers and colliders. Everything added to a scene is handled automatically, with optional init(), update() and draw() methods to define.

Example Scene code.

Parameters:

surfaceSize ((int, int)) – Restricts the size of the scene surface for improved performance (default = the size of the parent pygamepal.Game window).

addButton(button)

Adds a button to the scene.

Parameters:

button (pygamepal.Button) – The button to add.

addCollider(collider)

Adds a collider to the scene.

Parameters:

collider (pygamepal.Collider) – The collider to add.

addSprite(sprite)

Adds a sprite to the scene (and removes from other scenes).

Parameters:

sprite (pygamepal.Sprite) – The sprite to add.

addTrigger(trigger)

Adds a trigger to the scene.

Parameters:

trigger (pygamepal.Trigger) – The trigger to add.

draw()

Optional scene method called once per frame.

init()

Optional scene method called once when created.

onActive()

This method is called once when the scene becomes the current scene.

onInactive()

This method is called once when the scene is no longer the current scene.

removeButton(button)

Removes a button from the scene.

Parameters:

button (pygamepal.Button) – The button to remove.

removeCollider(collider)

Removes a collider from the scene.

Parameters:

collider (pygamepal.Collider) – The collider to remove.

removeSprite(sprite)

Removes a sprite from the scene.

Parameters:

sprite (pygamepal.Sprite) – The sprite to remove.

removeTrigger(trigger)

Removes a trigger from the scene.

Parameters:

trigger (pygamepal.Trigger) – The trigger to remove.

static sortByBottom(s)

Static method to sort sprites by their bottom position (y-position + height).

static sortByLayer(s)

Static method to sort sprites by their layer property.

static sortByLeft(s)

Static method to sort sprites by their left property (x-position).

static sortByRight(s)

Static method to sort sprites by their right position (x-position + width).

static sortByTop(s)

Static method to sort sprites by their top (y-position).

update()

Optional scene method called once per frame.

pygamepal.splitTexture

pygamepal.splitTexture.splitTexture(texture, newTextureSize, rows=0, columns=0, clippingRect=None)

Split a texture into a 2D list of sub-textures, using the given size. (Use pygamepal.flatten() to flatten the list returned into a single list.)

Parameters:

• texture (pygame.texture) – The original texture to split.

• newTextureSize ((int, int)) – The size (w, h) of each of the new textures.

• rows (int) – The number of rows down to split (default = 0, which means split all available rows).

• columns (int) – The number of columns scross to split (default = 0, which means split all available columns).

• clippingRect (pygame.Rect) – The (x, y, w, h) portion of the source image to split (default = None, which uses all of the source image).

Return list(list(pygame.texture)) newTextures:

The 2D list of new textures.

pygamepal.sprite

class pygamepal.sprite.Sprite(textureURL=None, texture=None, position=(0, 0), size=(0, 0), layer=0, scaleTexture=False, collider=None, trigger=None, drawColor='white')

Bases: Sprite

Example Sprite code.

Parameters:

• textureURL (str) – (default = None).

• texture (pygame.Texture) – The sprite texture (default = None).

• position ((int, int)) – The (x, y) position of the top-left of the sprite (default = (0, 0)).

• size ((int, int)) – The (w, h) size of the sprite (default = (0, 0)).

• layer (int) – The draw layer (0 = drawn first, default = 0).

• scaleTexture (bool) – Resize the texture to the sprite size (default = False).

• collider (pygamepal.Collider) – Specify a sprite collider (default = False).

• trigger (pygamepal.Trigger) – Specify a sprite trigger (default = False).

• drawColor (pygame.Color) – The color to draw the sprite outline (default = ‘white’).

drawWithoutParentScene(surface)

Call this draw method once per frame if using a sprite independently of a pygamepal.Game or pygamepal.Scene.

Parameters:

surface (pygame.Surface) – The surface to draw the sprite to.

getCenter()

Returns the center (x, y) position of a sprite, using its size.

init()

Optional, user-defined init method. Called automatically once upon creation if added to a pygamepal.Game or pygamepal.Scene, but should be called manually if used independently.

onAddedToScene(scene)

This method is run once when the sprite is added to a scene.

Parameters:

scene (pygamepal.Scene) – The scene that the sprite is being added to.

onRemovedFromScene(scene)

This method is run once when the sprite is removed from a scene.

Parameters:

scene (pygamepal.Scene) – The scene that the sprite is being removed from.

property position

Get / set the sprite position, taking any colliders into consideration.

touching(otherSprite)

Returns True if the sprites position / size intersencts with another sprite.

Parameters:

otherSprite (pygamepal.Sprite) – The sprite to check against.

update()

Optional, user-defined update method. Called automatically once per frame if added to a pygamepal.Game or pygamepal.Scene, but should be called manually if used independently.

updateWithoutParentScene(deltaTime=1)

Call this draw method once per frame if using a sprite independently of a pygamepal.Game or pygamepal.Scene.

Parameters:

deltaTime (float) – The time since the last update call (default = 1).

property x

Get / set the sprite x position.

property y

Get / set the sprite y position.

pygamepal.spriteImage

class pygamepal.spriteImage.SpriteImage(*textures, state=None, animationDelay=8, loop=True, hFlip=False, vFlip=False, offset=(0, 0), visible=True, alpha=255, pause=False)

Bases: object

Maps string states to a pygamepal.SpriteTextureList object containing textures and associated information.

Example SpriteImage code.

Parameters for the first provided state:

Parameters:

• textures (pygame.texture) – 0 or more textures to add to the first SpriteTextureList. Note that if more than 1 texture is added, the spriteImage becomes an animation.

• state (str) – The state name to associate with added textures (default = None).

• animationDelay (int) – The amount of time to display each texture (default = 8).

• loop (bool) – Loop animation (ignored if only one image provided for a state, default = True).

• hFlip (bool) – Horizontally flip images (default = False).

• vFlip (bool) – Vertically flip textures (default = False).

• offset ((int, int)) – Used to ignore part of the image when specifying a drawing position. Useful for sprites with whitespace or characters holding tools, etc. (default = (0, 0)).

Parameters for all states:

Parameters:

• visible (bool) – Show image (default = True).

• alpha (int) – The transparency value (between 0 and 255, default = 255).

• pause (bool) – Stops animation (ignored for states with only one image, default = False).

addTextures(*textures, state=None, animationDelay=8, loop=True, hFlip=False, vFlip=False, offset=(0, 0))

Add one or more textures to a (new or existing) state.

Parameters:

• textures (pygame.texture) – 0 or more textures to add to the first SpriteTextureList. Note that if more than 1 texture is added, the spriteImage becomes an animation.

• state (str) – The state name to associate with added textures (default = None).

• animationDelay (int) – The amount of time to display each texture (default = 8).

• loop (bool) – Loop animation (ignored if only one image provided for a state, default = True).

• hFlip (bool) – Horizontally flip images (default = False).

• vFlip (bool) – Vertically flip textures (default = False).

• offset ((int, int)) – Used to ignore part of the image when specifying a drawing position. Useful for sprites with whitespace or characters holding tools, etc. (default = (0, 0)).

property alpha

Get / set the current alpha value.

property center

Get the center positon for the current texture.

draw(surface, position)

Draws the current frame of the current state’s animation. Must be called once per frame.

Parameters:

• surface (pygame.surface) – The surface to draw to.

• position ((int, int)) – The (x, y) position to draw to (default = (0, 0)).

reset()

Clear object states and textures, and reset the object to default values.

property state

Get / set the current state.

update(deltaTime=1)

Updates the current sprite animation. Must be called once per frame.

Parameters:

deltaTime (float) – Time elapsed since last call (default = 1).

pygamepal.transition

class pygamepal.transition.Transition(fromSurface=None, toSurface=None, duration=100, easingFunction=None)

Bases: object

The base class for transitions between 2 surfaces. This class does not need to be used directly.

Example Transition code.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

reset()

update(deltaTime=1)

class pygamepal.transition.TransitionFade(fromSurface=None, toSurface=None, duration=100, easingFunction=<function easeLinear>)

Bases: Transition

Fade between 2 surfaces.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

class pygamepal.transition.TransitionFadeToBlack(fromSurface=None, toSurface=None, duration=100, easingFunction=None)

Bases: Transition

Fade to black between 2 surfaces.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

class pygamepal.transition.TransitionMoveDown(fromSurface=None, toSurface=None, duration=100, easingFunction=None)

Bases: Transition

Move down between 2 surfaces.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

class pygamepal.transition.TransitionMoveLeft(fromSurface=None, toSurface=None, duration=100, easingFunction=None)

Bases: Transition

Move left between 2 surfaces.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

class pygamepal.transition.TransitionMoveRight(fromSurface=None, toSurface=None, duration=100, easingFunction=None)

Bases: Transition

Move right between 2 surfaces.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

class pygamepal.transition.TransitionMoveUp(fromSurface=None, toSurface=None, duration=100, easingFunction=None)

Bases: Transition

Move up between 2 surfaces.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

class pygamepal.transition.TransitionWipeDown(fromSurface=None, toSurface=None, duration=100, easingFunction=None)

Bases: Transition

Wipe down between 2 surfaces.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

class pygamepal.transition.TransitionWipeLeft(fromSurface=None, toSurface=None, duration=100, easingFunction=None)

Bases: Transition

Wipe left between 2 surfaces.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

class pygamepal.transition.TransitionWipeRight(fromSurface=None, toSurface=None, duration=100, easingFunction=None)

Bases: Transition

Wipe right between 2 surfaces.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

class pygamepal.transition.TransitionWipeUp(fromSurface=None, toSurface=None, duration=100, easingFunction=None)

Bases: Transition

Wipe up between 2 surfaces.

Parameters:

• Surface (pygame.Surface from) – The surface to transition from.

• toSurface (pygame.Surface) – The surface to transition to.

• duration (float) – The time over which to transition between surfaces.

• easingFunction (func) – The easing function to apply to the transition (default = pygamepal.easeLinear).

draw(surface)

pygamepal.trigger

class pygamepal.trigger.Trigger(position=(0, 0), size=(10, 10), offset=(0, 0), onEnter=None, onCollide=None, onExit=None, drawColor='yellow')

Bases: object

A trigger defines an area that executes callback functions when colliding with other triggers.

Example Trigger code.

Parameters:

• position ((int, int)) – The (x, y) top-left position of the trigger (default = (0, 0)).

• size ((int, int)) – The (w, h) size of the trigger, in pixels (default = (10, 10)).

• offset ((int, int)) – The (x, y) offset from the parent pygamepal.Sprite position (default = (0, 0)).

• onEnter (func) – A function called once when two triggers first collide (default = None).

• onCollide (func) – A function called on every frame that two triggers collide (default = None).

• onExit (func) – A function called once when two triggers no longer collide (default = None).

• drawColor (pygame.Color) – The color to draw the trigger (default = ‘yellow’).

draw(surface)

Draw can be called to draw a trigger when used independently. (Note: this method is called automatically when pygamepal.DEBUG is True, when used as part of a pygamepal.Game or pygamepal.Scene)

Parameters:

surface (pygame.Surface) – The surface to draw to.

property h

Get / set the trigger height.

update(deltaTime=1)

Update must be called once per frame if used independently. (Note: does not need to be called if used as part of a pygamepal.Game or pygamepal.Scene)

Parameters:

deltaTime (float) – Time elapsed since last game tick (default = 1).

property w

Get / set the trigger width.

property x

Get / set the trigger x position.

property y

Get / set the trigger y position.

Module contents