[Wiki] Pokitto gaming API for Python, reference (uPyGame and umachine)

open-source
micropython

#1

The uPyGame gaming API

uPyGame (“micro PyGame”) is a PyGame like gaming API for Micro Python in Pokitto.

Python Modules, Classes and methods provided:

(internally implemented in C language).

The Rect class

  • Rect( x,y,w,h ) or Rect( rect ) - Create a rect
  • colliderect( rect ) - Checks if the given rect collides with it.
    • rect - The rect to check collision for.
  • x, y, width , height, centerx, centery - Rect data.

The event module

  • EventType poll() - Returns the next key event, or NOEVENT if no event found.
  • EventType.key - The key event data.
    • Values: K_UP, K_DOWN, K_LEFT, K_RIGHT, BUT_A, BUT_B, BUT_C
  • EventType.type - The key event data.
    • Values: KEYDOWN or KEYUP

The display module

  • init( clearAfterUpdate ) - Initialize the display.
    • clearAfterUpdate - True (default), if the screen buffer should be automatically cleared after the update() call.
  • set_mode() - Returns the screen surface.
  • flip() - Updates the screen and subsustems (audio, events, etc.). The same as update().
  • update( direct_draw_mode, update_rect, draw_now ) - Updates the screen and subsustems (audio, events, etc.).
    • direct_draw_mode - True, if the screen buffer should not be copied to the display HW. The default is false. (only in Hires 4-color mode i.e. “mode 1”)
    • update_rect - Only the update rect is copied to the display HW. The default is full screen. (only in Hires 4-color mode i.e. “mode 1”)
    • draw_now - If true, draws the screen surface immediately to the display, does not care about fps limits, do not run event loops etc. Default false.
  • set_palette( palette ) - Sets the palette with rgb colors.
    • palette - The list of (r,g,b) tuples.
  • set_palette16bit( palette ) - Sets the palette with 16-bit colors.
    • palette - The list of 16-bit integer color values.

The surface module

  • Surface( width, height, pixels ) - Create a surface.
    • widht, height - The surface size.
    • pixels - The array of pixel values.
  • Rect get_rect() - Returns the surface rect.
  • fill( color, rect ) - Fills the given rect with a color. (works for the screen surface only)
    • color - The fill color index.
    • rect - The rectangle to fill
  • blit( src_surface, x, y, transp_index(opt), horizFlip(opt), vertFlip(opt) ) - Draws the surface to the screen.
    • src_surface - The source surface.
    • x,y - The position on screen
    • transp_index - The index of the tranparent color. The default is 0.
    • horizFlip - If true, flip (mirror) the bitmap horizontally.
    • vertFlip - If true, flip (mirror) the bitmap vertically. Cannot be used at the same time as the horizFlip parameter.
  • setHwSprite( src_surface, palette, index, x, y, reset_dr, transp_index) - Defines a HW sprite (only in Hires 4-color mode i.e. “mode 1”).
    • src_surface - The source surface.
    • palette - The 4 color palette (list).
    • index- The sprite index.
    • x,y - The sprite position.
    • reset_dr - True, if the “dirty rect” should be reseted.
    • transp_index - The index of the tranparent color. The default is 0.
  • setHwSpritePos( index, x, y ) -Changes the HW sprite position (only in Hires 4-color mode i.e. “mode 1”).
    • index- The sprite index.
    • x,y - The sprite position.
  • set_clip( rect ) - Sets or removes the clipping rect for the screen surface. (only in Hires 4-color mode i.e. “mode 1”)
    • rect - The clip rect. If the argument is missing, the clip rect is removed.

The draw module

  • set_foreground_color( colorIndex ) - Set the foreground color.
    • colorIndex - The index of the foreground color.
  • set_background_color( colorIndex ) - Set the background color.
    • colorIndex - The index of the foreground color.
  • set_transparent_color( colorIndex ) - Set the transparent color.
    • colorIndex - The index of the foreground color.
  • rect( rect, isFilled, colorindex(opt) ) - Draw a rectangle.
    • rect - The Rect object.
    • isFilled - True, the rectangle is filled.
    • colorIndex - The color.
  • circle( x,y,r, isFilled,colorindex(opt) ) - Draw a circle.
    • x,y,r - The position and the radius.
    • isFilled - True, the circle is filled.
    • colorIndex - The color.
  • line( x0,y0,x1,y1,colorindex(opt) ) - Draw a line.
    • x0,y0,x1,y1 - The start and end positions of the line.
    • colorIndex - The color.
  • pixel( x,y,colorindex(opt) ) - Draw a pixel.
    • x,y - The position of the pixel.
    • colorIndex - The color.
  • text( x, y, string, colorIndex ) - Draw text (the same as umachine.draw_text()).
    • x, y - The text position
    • string - The text.
    • colorIndex - the color.

The tilemap.Tilemap class

  • Tilemap( width, height, map_data ) - Constructor. Creates the tilemap.
    • widht, height - The tilemap size in tiles.
    • map_data - The array of map values, i.e. tile indices. Each 8-bit value contains two tile indices.
  • set_tile( index, width, height, pixel_data ) - Set a tile.
    • index - The index for the tile. Must be between 0 and 15 (inclusive).
    • widht, height - The tile size in pixels.
    • pixel_data - The pixel data of the tile as 4-bit pixels. Each 8-bit value contains two pixels.
  • tileId = get_tile_id( x, y, tileSize )
    • x, y - The position on the tilemap in pixels.
    • tileSize - The size of a tile. There are speed optimized versions for 8 and 16 bit tile sizes.
    • tileId - The id of the tile on position (x,y). The value of the id is between 0 and 15.
  • tileIdList = get_tile_ids( topLeftX, topLeftY, bottomRightX, bottomRightY, tileSize ) - The list of the tile ids of the four corners of collision rectangle.
    • topLeftX, topLeftY, bottomRightX, bottomRightY - The position of the top left and bottom right corners of the collision rectangle on the tilemap in pixels.
    • tileSize - The size of a tile. There are speed optimized versions for 8 and 16 bit tile sizes.
    • tileIdList - The list of the tile ids of the four corners of collision rectangle. The value of the each id is between 0 and 15.
  • draw( x, y ) - Draw the tilemap.
    • x, y - The position of the tilemap on the screen.

The mixer.Sound class (The audio can only be heard on the HW)

  • Sound() - Constructor. Resets the audio stream and starts playing an empty stream.
  • reset - Resets audio.
  • fill_buffer - Fills the buffer with audio data.
  • get_current_soundbuffer_index - Gets current sound buffer index.
  • get_current_soundbuffer_pos - Gets current position in the buffer.
  • get_soundbuffer_size - Gets the size of the sound buffer
  • play - Starts playing.
  • pause - Pauses playing.
  • play_sfx( audioData, length, is4BitFormat ) - Play the sound data.
    • audioData - Audio data
    • length - The length of the audio data buffer.
    • is4BitFormat - True, if the sound data is in 4 bit format. False, if the sound data is in 8 bit format.
  • play_from_sd( fileName ) - Play the music from the SD card.
    • fileName - The name of the raw, mono, 8-bit, 8 kHz music file in the SD card.

Additional Python classes

(implemented in Python language in a separate *.py file)

Sprite.py:

  • The Sprite class (different from HwSprite above). See the class for method descriptions.

Usage

Look for an usage in the Mars Attack game, where almost every module and class is used in

The umachine module

This is a collection of utility functions

Miscellaneous functions

  • mem8[ address ], mem16[ address ], mem32[ address ] - Physical memory access
  • draw_text( x, y, string, color) - Draw text on the screen.
    • x, y - The text position
    • string - The text.
    • color - the color index.
  • wait( time_ms ) - Wait for a given time.
    • time_ms - The time milliseconds to wait.

GPIO pin control methods

Pin( pin_number, pin_direction ) - Create the pin object.
value() - Get the pin input value.
off() - Set the pin value to 0.
on() - Set the pin value to 1.
IN - The pin direction.
OUT - The pin direction.
EXT0...EXT17 - The pin number.


[Tutorial]How to make a simple game in Python: "Frogitto"
FAQ: Python in Pokitto
[Release & Competition] Online Python Editor for Pokitto!
Release notes of the Online Pokitto Python Editor
[Release & Competition] Online Python Editor for Pokitto!
FAQ: Python in Pokitto
#2

Is there a way to draw transparent sprites? How set transparent color?


#3

Normally the first color of the palette of the sprite is the ‘transparent color’


#4

Correct, the default tranparent color index in blit(j is zero. You can also give another index as the last parameter. Updated the wiki.


#5

It works. Thanks both @sbmrgd and @Hanski


#6

Is there some sort of time elapsed function to make the game loop update at fixed time?


#7

Unfortunately, not currently.


#8

@Hanski , do we have a setpixel of any sort ?


#9

I do not think so. Pixel level operations might anyway be a bit slow with Python as there is more overhead per call than in C++.


#10

@Hanski HELP!! Directional buttons work but A,B,C do not (pyinsky editor)

if eventtype.key == upygame.K_BUT_A:
                if (ship_landed == 2):
                    initgame()

Results in

Traceback (most recent call last):

File “main.py”, line 478, in <module>

AttributeError: no such attribute


#11

it’s upygame.BUT_A


#12

Yes, that was a mistake in the top post. Fixed now.


#13

umachine.time_us() is missing. The value returned is ms or us ?


#14

You are correct, it is milliseconds. I have to fix the name and add to the documentation.


#15

Isn’t this supposed to take 3 parameters? It’s missing audioData’s length.


#16

Yes, fixed that. Thanks!