[Wiki] Reference: Pokitto gaming API for Python (uPyGame and umachine)

THE UPYGAME GAMING API

uPyGame (“micro PyGame”) is a PyGame like gaming API for Micro Python in Pokitto. To use it add import upygame to the Python program.

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.
  • 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.

Buffered screen modes

Python can be used in buffered HighRes (220x176, 4 colors) or LowRes (110x88, 16 colors) modes.

TAS screen modes (bufferless)

Read the documentation here: https://pokitto.github.io/library/upygamereference

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 UTILITY API

This is a collection of utility functions. To use it add import umachine to the Python program.

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.
  • time_ms() - Return the current time in milliseconds.

The Cookie class

The Cookie class can be used to save and load data from EEPROM memory. The EEPROM memory preserves its content even if the device is switched off. Use it to store a small amount of data only as the memory is shared between all other applications also. There are total 4 kb of EEPROM memory in Pokitto.

Methods:

  • Cookie( name, cookie_data ) - Constructor. Creates the cookie of the given name and given data size.
    • name - The name of the cookie (max 8 characters). This identifies the cookie in EEPROM.
    • cookie_data - The byte array where the cookie data is stored.
  • save( ) - Saves the cookie data in the byte array to EEPROM.
  • load( ) - Loads the cookie data from EEPROM to the byte array.

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.
9 Likes

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

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

1 Like

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

1 Like

It works. Thanks both @sbmrgd and @Hanski

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

Unfortunately, not currently.

1 Like

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

1 Like

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++.

2 Likes

@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

it’s upygame.BUT_A

1 Like

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

1 Like

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

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

1 Like

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

2 Likes

Yes, fixed that. Thanks!

Is it possible to set the pin mode? for example input pullup?

1 Like

Added TAS related info to the top post.

1 Like

Moved TAS info to the new documentation repository here: https://pokitto.github.io/library/upygamereference

Added a full example and a screenshot for the methods.

4 Likes