micropython-appengine

A MicroPython app engine.

This module works under MicroPython and it is tested with MicroPython V1.19.1.

Installation

>>> import upip
>>> upip.install('micropython-appengine')

Alternatively just copy appengine.py to the MicroPython device.

Usage

• Subclass InputDevice for the input device.
• Subclass Screen for the screen.
• Subclass Sprite for all the sprites needed in the app.
• Subclass Manager for the app main control.

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.