Skip to content

API Reference#

A MicroPython app engine.

  • Author: Quan Lin
  • License: MIT

AppEngineException #

Bases: Exception

A class for appengine exception.

InputDevice() #

A class for the input device.

Note

This class needs to be subclassed to be useful. Override __init__() to initialise the input device. Override update() to implement the logic of the input device.

update() #

This method should implement the logic of the input device.

It is called before every frame by the manager.

Raises:

Type Description
AppEngineException

An error occurred when this class is not subclassed.
Note

This method must be overridden by a subclass.

Manager() #

A class for app manager.

Attributes:

Name Type Description
DEFAULT_TARGET_FPS int

20, default target FPS (frames per second).
input_device InputDevice

The input device.
screen Screen

The screen.
sprite_list list

The list holding all the available sprites.
target_fps float

The target FPS.
actual_fps float

The actual FPS.
running bool

The flag indicating the app is running or not.
Note

This class needs to be subclassed to be useful. Override __init__() to initialise the manager. Override update() to implement the logic of the manager.

add_sprite(sprite) #

Add a sprite to the manager.

Parameters:

Name Type Description Default
sprite Sprite

The sprite to be added to the manager.

 required

arun() async #

Run the app asynchronously with uasyncio.

exit() #

Exit the app.

get_sprites(cls=Sprite, name=None) #

Get a filtered list of sprites.

Parameters:

Name Type Description Default
cls type

The class of the sprites that should be returned.

 Sprite
name str

The name of the sprites that should be returned.

 None

Returns:

Type Description
list[Sprite, ...]

A list of selected sprites.

kill_sprites(cls=Sprite, name=None) #

Kill a filtered list of sprites.

Parameters:

Name Type Description Default
cls type

The class of the sprites that should be killed.

 Sprite
name str

The name of the sprites that should be killed.

 None

run() #

Run the app.

update() #

This method may implement the logic of the manager.

It is called before every frame. A very simple app may not override it.

Screen() #

A class for the screen.

Attributes:

Name Type Description
display FrameBuffer

A display object whose class is a subclass of FrameBuffer. For example, an SSD1306 driver object.
w int

The width of the screen in pixel.
h int

The height of the screen in pixel.
camera_target Sprite

If not None, the screen camera will follow this sprite. The center of this sprite will be placed at the center of the screen.
Note

This class needs to be subclassed to be useful. Override __init__() to initialise the screen. Override update() to show the content of the screen from its buffer.

blit(sprite) #

Blit the sprite at its position in the screen.

It is called before every frame for each sprite added to the manager.

Parameters:

Name Type Description Default
sprite Sprite

A sprite to be placed in the screen at its position.

 required

clear() #

Clear the screen buffer and update it.

flip() #

Update the screen and clear the screen buffer.

It is called before every frame by the manager.

update() #

This method should show the content of the screen from its buffer.

For example, the show() method of an SSD1306 driver can be called here.

Raises:

Type Description
AppEngineException

An error occurred when this class is not subclassed.
Note

This method must be overridden by a subclass.

Sprite() #

A class for app sprites.

Attributes:

Name Type Description
UP int

1, direction up.
LEFT int

2, direction left.
DOWN int

3, direction down.
RIGHT int

4, direction right.
x float

The x position of the sprite.
y float

The y position of the sprite.
w int

The width of the sprite in pixel.
h int

The height of the sprite in pixel.
vx float

The x velocity of the sprite.
vy float

The y velocity of the sprite.
imgs list

The list of images to represent the sprite. A sequence of images can make animation.
img_idx int

The index of the image to be shown.
img_fpstep_counter int

Frames per step counter for animation.
colourkey int

Transparent colour, -1 means no transparent colour.
is_overlay bool

If True, the sprite is ignored by screen camera.
manager Manager

The manager of the app. When a sprite is added to the manager, this attribute is set automatically.
name str

The name of the sprite.
killed bool

If True, the sprite will be removed by the manager.
Note

This class needs to be subclassed to be useful. Override __init__() to initialise the sprite. Override update() to implement the logic of the sprite.

check_collision(other) #

Check collision with the other sprite.

This is a simple example of collision detection. It can be overridden with other implementation. When there is no collision detected, it returns None. When collision is detected, a 2-tuple is returned. The first element indicates where the collision happened. It could be Sprite.UP, Sprite.LEFT, Sprite.DOWN or Sprite.RIGHT. The second element indicates how deep the collision is in pixel.

Parameters:

Name Type Description Default
other Sprite

The other sprite to check collision with.

 required

Returns:

Type Description
tuple[int, int]

A 2-tuple or None.

clamp_position(up=None, left=None, down=None, right=None) #

Clamp the position of the sprite.

This method clamps the position of the sprite. The size of the sprite is taken into account. The up and left limits are inclusive. The down and right limits are exclusive. When there is conflict in left and right limits, the left limit overrides. When there is conflict in up and down limits, the up limit overrides.

Parameters:

Name Type Description Default
up float

Up limit of the up side of the sprite.

 None
left float

Left limit of the left side of the sprite.

 None
down float

Down limit of the down side of the sprite.

 None
right float

Right limit of the right side of the sprite.

 None

clamp_velocity(vx_min=None, vx_max=None, vy_min=None, vy_max=None) #

Clamp the velocity of the sprite.

Parameters:

Name Type Description Default
vx_min float

Min limit of x velocity of the sprite.

 None
vx_max float

Max limit of x velocity of the sprite.

 None
vy_min float

Min limit of y velocity of the sprite.

 None
vy_max float

Max limit of y velocity of the sprite.

 None

get_layer() #

Get the layer in which the sprite is located.

A larger number means the sprite is in a more upper layer.

Returns:

Type Description
int

The layer in which the sprite is located.

kill() #

Kill the sprite, so it will be removed by the manager.

kill_after_n_frames(num) #

Kill the sprite in a delayed manner.

Parameters:

Name Type Description Default
num int

The number of frames after which the sprite will be killed. For example, given 20 FPS, setting 40 will kill the sprite after 2 seconds.

 required

set_layer(layer) #

Set the layer in which the sprite is located.

A larger number means the sprite is in a more upper layer.

Parameters:

Name Type Description Default
layer int

The layer in which the sprite is located.

 required

setup_animation(start, length, fpstep) #

Setup animation for the sprite.

Parameters:

Name Type Description Default
start int

The start index of the images for animation.

 required
length int

The length of the images for animation.

 required
fpstep int

Frames per step for animation speed.

 required

update() #

This method may implement the logic of the sprite.

It is called before every frame. A passive sprite may not override it.